Players and possession

A player is an entity carrying a PlayerController: a seat at the machine, an aim, and nothing that describes a thing in the world. A pawn is any entity it is currently driving. Player is the operation set that links the two, and MoveIntent is what the link carries.

The three pieces are separate because they have different lifetimes. A pawn dies. A controller does not — it keeps its slot, its connection, its camera channel and, most importantly, where the player was looking.

Anything a person drives: a character, a vehicle, a spectator camera, a cursor in a strategy game. The reason to use it rather than a script on the character is respawning. With a controller, a respawn is Player.Possess(world, controller, newPawn) — one call, and the aim, the score and the camera follow by themselves. Without one, every game rediscovers that those five things have to be copied across the gap, and each rediscovery misses a different one.

It is also what an AI shares with a human. Nothing downstream of MoveIntent knows which is driving, so a possessed NPC and a possessed player run the same movement code.

You do not want it for something nobody drives — a door, a turret on a timer, a projectile. Those write their own components, and a pawn nothing possesses is never visited.

Three components and one call:

Player.Create gives the entity a PlayerController, a ControlRotation and a MoveIntent. Possess writes the Possessing/PossessedBy pair, releasing whatever either side was already attached to — so possessing a pawn somebody else holds steals it rather than sharing it.

Two systems make it move. PlayerInputSystem samples each player's input source into their aim and their intent; PossessionSystem copies that intent onto the pawn, points the camera at it, and lets go of pawns that no longer exist. Both run in SystemPhase.Input, before the fixed step that reads the result.

Where intent comes from is an interface. IPlayerInputSource has one method, so a device, a planner, a replay and a test are the same shape:

ActionPlayerInput is the one the engine ships, over a Vixen.Input action map. It wants a Move and a Look value action and binds any of Jump, Crouch, Sprint, Fire, AltFire, Aim, Interact and Reload that the map happens to have. A missing Move or Look throws at construction naming the map and the action, rather than reading zero on the frame the player presses it.

⚠ MoveIntent.Move.Y is forward, and Vixen.Input's vector2 composite reports up as negative. Those are two different conventions — one describes a direction of travel, the other a screen — and ActionPlayerInput is the single place they meet, so it negates the Y it reads. A source of your own owes the same flip: Move = (0, 1) has to mean forward, because WorldDirection multiplies it by a forward vector. Copying the composite straight through walks the player backwards, and the symptom reads as "W and S are swapped" rather than as a sign.

A shipping game should implement IPlayerInputSource over its own generated accessor. ActionPlayerInput binds by name, which is the one thing Vixen.Input otherwise makes impossible: a renamed action becomes a run-time surprise instead of a compiler error. The engine cannot reference a game's generated class, so the default is the compromise; the interface is the way out of it, and it is the eight lines above.

The camera is one call. PlayerCameras assembles the two rigs a player steers:

ThirdPerson also puts a CameraOcclusion on the shot, at the same pivot its body and aim stages use. It does nothing until the host answers for it — what a camera may pass through is a question about a world's solidity, and Vixen.Engine references no physics — so the one line a game with a physics scene writes is:

⚠ Set CameraOcclusion.PivotOffset to match the rig, which ThirdPerson does for you. The sweep starts at whatever the shot looks at, and a character's origin is at their feet — so a probe of any radius begins inside the floor, reports an obstruction at zero distance, and pins the camera at MinimumDistance for ever. That reads as broken damping rather than as a ray starting in the ground.

Each creates a real Camera with a CameraDirector on the player's own channel, a VirtualCamera shot on the same channel, and binds the shot. From then on PossessionSystem points the shot at whatever the player is driving and feeds it their aim, every frame — so a death, a respawn and a vehicle entry all need no camera code at all.

These two are in the engine rather than in a sample because they are the rigs that cannot be built from outside it: both are steered by ControlRotation, and the write that carries it into PovAim and OrbitBody is PossessionSystem's. Everything a game tunes is an argument here and a component afterwards, so a third rig is the same three component adds with different values.

You can also do it by hand, which is what those two calls are:

⚠ FollowBody.Behind swings round as the target turns, which is right for a camera watching a car and wrong for one a player is steering — that is why ThirdPerson uses OrbitBody instead.

Respawning. The controller is what survives, so nothing has to be carried across:

Destroying a pawn without unpossessing is fine. PossessionSystem clears the dangling edge on its next pass and counts it in ReleasedCount — a number that climbing every frame means a game is leaking possessions.

Split screen. Two seats, two gamepad slots, two camera channels, one world:

⚠ The two things that stopped this drawing are built; the frame document is not. CameraExtractionSystem used to fill one RenderView from the lowest Camera.Order, and a RenderView had no viewport rectangle. Both are gone: Camera.ViewportRect is the rect, CameraExtractionSystem.Rank fills one view per seat, and SingleStageRenderer narrows the viewport and the scissor to each. The order still decides which seat is which, so swapping who is on top is still an order write.

⚠ What a game still has to do itself is the tree. !StandardFrame binds one view throughout — shadows, the froxel grid, SSAO and every post effect — so there is no two-seat frame document to load yet, and a host wanting one assembles a compositor with a RenderView and a CameraExtractionSystem per seat. PlayerCameras.SplitScreen writes the rects and stops there.

Reading the intent. Movement code sees a component, not a controller:

WorldDirection uses the yaw and never the pitch, so a character walking forward while looking at the sky walks along the ground.

Stopping input without losing the player. A cutscene sets one field:

The intent is cleared rather than frozen, so a held sprint does not survive the cutscene — and the aim is untouched, because that is the thing the controller exists to preserve.

• Components — why Possessing, PossessedBy and ViewTarget carry [Component] without [DataContract], and what that keeps out of a scene file.
• Entity queries — how a movement system reads MoveIntent a column at a time.
• Getting content into a running game — what a build has to know before a level can name the components a game like this declares.

The design record is docs/plan/29-players-and-possession.md, which carries the argument for the decomposition and what P1 to P4 add: character movement, the assembled camera rigs, the networked and predicted half, and the sample. The shots and the director a ViewTarget points into are docs/plan/26-virtual-cameras.md.