Scene & Gameplay

The scene system is designed to be:

• explicit
• editor-friendly
• flexible enough for both simple games and complex simulations

1. The Scene as the Runtime Context

A Scene represents the active world state.

this.Scene = new Scene3D();
Scene.Init(Viewport, RenderDevice);

A scene owns:

• all game elements
• the physics handler
• lighting and environment
• render targets and render statistics

Only one scene is active at a time, but scenes can be created, destroyed, or swapped freely.

2. GameElements: The Building Blocks

Everything that exists in a scene is a GameElement.

Examples:

• Primitive
• StaticModel
• AnimatedModel
• LightHandle
• Empty (logic-only objects)

Scene.AddGameElement(ground);
Scene.AddGameElement(Player);

Core Properties

Every GameElement has:

• a Transform
• a Name
• a lifecycle (Init, Update, Render, Dispose)
• optional children
• optional behaviors

This makes all elements uniformly manageable.

3. Hierarchies & Transform Propagation

Game elements can form parent-child hierarchies.

Player.AddChild(new StaticModel("BlasterViewmodel", _viewModelMesh));

Key rules:

• Child transforms are relative to their parent
• World transforms are resolved automatically
• Moving the parent affects all children

This is essential for:

• player models
• weapons
• cameras
• attachments

4. Behaviors: Gameplay Logic Composition

Gameplay logic is attached via behaviors, not inheritance.

Player.AddBehavior(new FPSController());
Player.AddBehavior(new CapsuleRigidBody(PhysicsHandler));

Why Behaviors?

• No deep inheritance trees
• Logic is reusable
• GameElements stay data-oriented
• Systems stay decoupled

A behavior can:

• react to updates
• interact with physics
• modify transforms
• communicate with other components

5. Physics as a First-Class System

Physics is integrated at the scene level.

this.PhysicsHandler = new PhysicsHandler3D(gravity);
Scene.PhysicsHandler = this.PhysicsHandler;

Colliders and rigid bodies are added as behaviors:

var collider = ground.AddBehavior(new BoxCollider(PhysicsHandler));
collider.CreateCollider(0);

Design Philosophy

• Physics is explicit
• No automatic collider generation
• Debug rendering is optional
• Physics can be disabled per scene

This makes physics predictable and editor-safe.

6. Scene Update Order

Each frame follows a deterministic order:

1. Physics update
2. Scene update
3. GameElement updates
4. Behavior updates

Scene.UpdatePhysics(deltaTime);
Scene.Update(deltaTime);

This guarantees:

• stable simulation
• consistent behavior mention
• deterministic gameplay

7. Runtime Safety: Add vs Enqueue

Important Rule

Scene structure must NOT be modified directly during the frame loop.

Do not do this inside Update or Render:

Scene.AddGameElement(element);
Scene.RemoveElement(element);

Doing so would:

• invalidate iterators
• cause unstable behavior
• break editor/runtime parity

8. Enqueue System (Mid-Frame Safe Modifications)

All runtime changes must be enqueued and processed at the end of the frame.

Example: Spawning a Projectile During Gameplay

private void SpawnProjectile(BaseScene scene, Vector3 position, Vector3 direction)
{
    var instancer = scene.FindElement<MeshInstancer>("ProjectileInstancer");
    if (instancer != null)
    {
        var instance = instancer.FindHiddenInstances(1).FirstOrDefault();
        if (instance != null)
        {
            var enqueEntry = new EnqueScene3DEntry()
            {
                Element = instancer.CreateInstanceHandle(instance),
                EnqueAction = enque_element,
                ExtraData = new Dictionary<string, object>()
                {
                    { "position", position },
                    { "direction", direction }
                }
            };

            scene.EnqueEntries.Add(enqueEntry);
        }
    }
}

What happens here?

1. A pooled instance is requested
2. The instance is not activated immediately
3. A scene entry is created
4. The entry is queued for processing
5. The scene applies the change after the frame

9. Frame-End Synchronization

All queued operations are applied at the end of the frame:

public override void OnFrameEnd()
{
    Scene.EnqueElements();
}

This ensures:

• safe element creation and removal
• synchronized physics and rendering
• consistent scene state for the next frame

10. Rule of Thumb

Quote

Before the loop → Add
Inside the loop → Enqueue

Summary

The Scene & Gameplay system in GFX-Next is built around:

• a single authoritative scene
• uniform GameElements
• behavior-based gameplay logic
• explicit physics integration
• a safe enqueue system for runtime changes

This approach keeps gameplay code predictable, editor-safe, and stable under complex runtime behavior.