behavior_On_Cursor_Direction

Directional Cursor Trigger (Relative to Node)

This behavior transforms a 3D object into a reference point for mouse interactions. It detects where the mouse cursor is located relative to the object's position on the screen (Up, Down, Left, or Right) and triggers specific actions when that direction changes.

This is particularly useful for top-down games, character orientation systems, or interactive "eye-tracking" effects where an object needs to react to the cursor's position.

Parameters

• On_Cursor_Up_Do_Action (action) Action triggered when the mouse moves above the object.
• On_Cursor_Right_Do_Action (action) Action triggered when the mouse moves to the right of the object.
• On_Cursor_Down_Do_Action (action) Action triggered when the mouse moves below the object.
• On_Cursor_Left_Do_Action (action) Action triggered when the mouse moves to the left of the object.
• Display_Cursor_On_Screen (bool, default = true) Determines if the system mouse cursor remains visible or is hidden while this behavior is active.

Behavior

1. 3D to 2D Projection: The script calculates the 2D screen coordinates of the target 3D Scene Node.
2. Quadrant Detection: It compares the mouse position to this center point to determine the dominant direction (Vertical vs. Horizontal).
3. Anti-Flicker (Hysteresis): A built-in threshold prevents the actions from "flickering" rapidly when the mouse is close to the diagonal lines separating the sections (e.g., exactly between Up and Right).
4. State Change Trigger: The actions are only executed once when the direction changes (e.g., moving from "Left" to "Up"). It does not spam the action every frame.

Example Use Cases

• Top-Down Character Animation: Change the sprite or animation of a character to face the mouse cursor (Up, Down, Left, Right).
• Combat Stance System: In an RPG, change the player's guard direction based on where the mouse is relative to the hero.
• Interactive Props: Create a 3D face or eye that looks in the direction of the user's cursor.
• Menu/UI Navigation: Trigger selection highlights based on mouse proximity to a central button.

Limitations

• Visibility: The node must be visible on the screen. If the node is behind the camera or outside the viewport, the script pauses calculations to prevent errors.
• Screen Space: The calculation is done in 2D screen space (pixels), not 3D world space.