FlexCam Example Scene

This example scene demonstrates all three camera modes available in the FlexCam addon:

• Observer Mode (RTS-style free camera)
• Follow Mode (Third-person follow camera)
• First Person Mode (FPS-style direct control)

Running the Example

1. Open the project in Godot 4.x
2. Make sure the FlexCam plugin is enabled (Project → Project Settings → Plugins)
3. Run the project (F5) or open example_scene.tscn and press F6

Scene Contents

Files Created

• example_scene.tscn - Main example scene
• example_controller.gd - Scene controller managing camera modes
• example_player.gd - Blue capsule that can be controlled (First Person Mode)
• example_unit.gd - Orange box that wanders autonomously (Follow Mode)
• EXAMPLE_README.md - This file

Scene Elements

1. Blue Player Capsule (Left side)

   • Click to take direct control
   • Demonstrates First Person Mode
   • Changes to green when controlled

2. Orange Unit Box (Right side)

   • Click to follow this unit
   • Demonstrates Follow Mode
   • Wanders around autonomously
   • Changes to yellow when selected

3. Ground Plane

   • 50x50 unit walkable surface
   • Provides collision for physics

4. FlexCam3D

   • Starts in Observer Mode
   • Automatically switches modes based on interaction

5. UI Panel

   • Shows current camera mode and target
   • Lists all controls
   • Describes each camera mode

Controls

Universal Controls

• WASD - Move camera or controlled entity
• Middle Mouse Button - Rotate camera (hold and drag)
• Mouse Wheel Up/Down - Zoom in/out (Follow and Observer modes)
• Left Click - Select or control entities
• Right Click - Release control (returns to previous mode)

Mode-Specific Controls

Observer Mode (Default)

• Free-flying RTS-style camera
• WASD moves the camera freely
• Middle mouse button to rotate
• Mouse wheel to zoom in/out
• Can click entities to enter other modes

Follow Mode (Click Orange Unit)

• Camera follows the selected unit from behind
• Unit continues to move autonomously
• Middle mouse button to orbit around unit
• Mouse wheel to zoom in/out
• WASD stops following and enables free-fly
• Right-click to return to observer mode

First Person Mode (Click Blue Player)

• Direct control of the player entity
• Mouse moves the camera (cursor hidden)
• WASD moves the player
• Space bar to jump
• Player capsule turns green when controlled
• Right-click to release control

How Camera Modes Are Triggered

The example uses callbacks to determine which mode should be active:

# Control callback - triggers First Person Mode
camera.should_control_callback = func(target: Node3D) -> bool:
    return target == controlled_entity

# Follow callback - triggers Follow Mode  
camera.should_follow_callback = func(target: Node3D) -> bool:
    return target == selected_entity and target != controlled_entity

Testing Each Mode

Test Observer Mode

1. Run the scene
2. Press WASD to move the camera around
3. Hold middle mouse button and move mouse to rotate
4. Scroll mouse wheel to zoom
5. This is the default RTS-style overview camera

Test Follow Mode

1. Left-click on the orange box
2. Camera smoothly transitions to follow it
3. Box continues wandering around
4. Hold middle mouse to orbit the camera
5. Press WASD to stop following and free-fly
6. Right-click to return to observer mode

Test First Person Mode

1. Left-click on the blue capsule
2. Camera smoothly transitions to first-person view
3. Mouse cursor is hidden (captured)
4. Move mouse to look around
5. Press WASD to walk, Space to jump
6. Capsule turns green to show you're in control
7. Right-click to release control

Understanding the Code

example_controller.gd

Main scene controller that:

• Sets up camera callbacks
• Handles entity selection (raycasting on left-click)
• Manages controlled/selected state
• Updates UI information

example_player.gd

Controllable player entity:

• Only processes movement when in "controlled" group
• Uses CharacterBody3D physics
• Visual feedback (color change) when controlled

example_unit.gd

AI unit that can be followed:

• Wanders autonomously using simple AI
• Continues moving even when being followed
• Visual feedback (color change) when selected

Integration Tips

This example demonstrates a simple integration pattern. For your own game:

1. Define clear states: Use groups, flags, or components to track entity state
2. Set up callbacks: Tell the camera how to determine which mode to use
3. Handle state changes: Update your entities when camera mode changes
4. Connect signals: Listen to camera events for game-specific logic

See addons/FlexCam/README.md for more integration examples and API documentation.

Troubleshooting

Camera not responding to mouse:

• Make sure input actions are configured in Project Settings → Input Map
• Check that no other scripts are consuming input events

Entities not clickable:

• Verify collision shapes are present on entities
• Check that entities have CharacterBody3D or similar physics body

Wrong camera mode activating:

• Review callback logic in example_controller.gd
• Print debug info to verify entity states

UI not visible:

• Check that UI layer is on top (should be last child in scene tree)
• Verify Panel visibility in scene editor