Players and possession

What it is#

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.

What it is for#

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.

Using it#

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.

Examples#

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:

⚠ That simulates, and only seat zero is drawn. Each player gets their own director, shots and camera, and all of it updates independently — but CameraExtractionSystem fills one RenderView from the lowest Camera.Order in the world, and a RenderView has no viewport rectangle. PlayerCameras sets each camera's order from its channel, so seat zero is on screen and swapping which player is watched is an order write. Showing both at once needs a view per player and a rect on each, which is the rendering pipeline's work rather than this subsystem's.

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.

See also#

• 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.