See !111

[[TOC]]

This adds the ability to have Pozyx (and PTrack) input entities work as cursors that can "inhabit" a character.

Pozyx inputs appear initially as a randomly colored dot. They can then move around the screen and walk through any uninhabited character to inhabit it and control it. The character will remain inhabited until either the pozyx entity drops out or the character is made inert (killed).

The cursor feature is necessary for the Moth activity: students controlling pozyx tags that persist across rounds need to selectively inhabit pre-spawned characters at the beginning of each round. This allows the system to spawn agents and give the class time to inspect the agents before students take over the character and the simulation is run. In contrast, the default Pozyx input behavior is to immediately spawn a new agent upon the appearance of the tag.

A Cursor can inhabit an agent either:

1. During "PREP ROUND > PICK CHARACTERS"

or

2. After "START ROUND".

When designing rounds, it is important to be aware of how cursors behave across rounds. Cursors will remain linked to their targets until either:

a) the target agent is deleted (e.g. via Population's removeAgent or removeInertAgents call.

--or--

b) the target agent is released via Population's releaseAllAgents or releaseInertAgents call.

Implications:

• By default, cursors will remain linked to their target agents across rounds. No need to do anything.

• If you want users to pick new targets with each round, you need to explicitly call releaseAllAgents in the initScript of the round.

The Cursor Feature is actually implemented by injecting a special Cursor blueprint into the project. Pozyx inputs are automatically mapped to these Cursor characters. The Cursor characters then have the ability to take over the movement of other characters that have enabled Cursor inhabiting.

Check out gs_packages/gem-srv/src/modules/sim/features/feat-cursor.ts to see how it's done. The actual position setting is handled by the Movement feature during m_FeaturesThink.

You can even edit the Cursor blueprint if you want to change how it looks or behaves.

graph TD

    subgraph Moth
    J[GEMSCRIPT] --> K[SCRIPT_TO_INSTANCE]
    K --> L[agent Moth]
    L --> S[Movement Feature: position]
    end

    subgraph Cursor
    M[pozyx] --> N[POZYX_TO_COBJ]
    N --> O[COBJ_TO_INPUTDEF]
    O --> P[INPUTDEF_TO_AGENT]
    P --> Q[agent Cursor]
    Q --> T[Movement Feature: position]
    T --> S
    end

Making a character controllable via a cursor is very simple.

1. Add useFeature Cursor to the character's blueprint.

This will automatically inject the special Cursor blueprint and make the character available for control by a cursor.

2. Remove isPozyxControllable for the agent if it's set.

Otherwise when they appear as a pozyx tag, they will automatically be directly assigned to the agent.

Multiple blueprints per project may enable Cursor use. e.g. you an enable cursors for both Moths and Predators. With Pozyx's reliable ID, retaining the connection between a cursor and a character is fairly solid. PTrack might be problematic.

The Cursor feature requires Movement.

# BLUEPRINT Moth
# PROGRAM DEFINE
useFeature Movement
useFeature Cursor

Things to watch out for:

• Remove any unnecessary Movement methods from characters that are supposed to be controlled by a cursor. Otherwise they may suddenly come to life and ignore the cursor controls.
• Cursor controls around stage boundaries might be problematic, especially if there is bounce or wrapping active.

The cursorTargetId is the agent id of the character that the cursor is controlling. Generally you do not want to edit this directly (results might not be what you expect since it is set internally by the Cursor feature), but you can use this to look up the value of the property, e.g.

ifFeatProp agent.Cursor.cursorTargetId equal '10' [[...]]

Use this method when a character dies and you want to release the cursor so it can go pick up other characters.

featCall Cursor releaseCursor

This is generally made on the character that is inhabited. e.g. if a Moth is being inhabited and dies, you would call this while setting the Moth inert.

The released cursor is then free to pick up other characters.

You can also use the Population Feature's releaseAllAgents and releaseInertAgents to release cursors en mass.