makepad/skills/makepad-gameplay-systems/SKILL.md

name	description
makepad-gameplay-systems	Design and implement Makepad game loops: entities, movers, rigid bodies, terrain, input, camera, physics, AI brains, racing, scoring, netplay and feel. Use for core loop, level design, controls, collision, character/vehicle handling, NPC behaviour, multiplayer session, and game-feel work on makepad-game-sim, makepad-game-blocks, makepad-game-script and makepad-game-session.

Makepad Gameplay Systems

Build the loop that makes it a game: something the player does, a reason to do it, and a state that ends.

Before implementing

Write the contract down. Four lines, in artifacts/game-progress.md:

• Core loop — one sentence: what the player repeatedly does and why it escalates.
• Win / lose — both reachable, both testable, both observable in a log line.
• Input map — every action, on every target device you claim to support.
• Camera scale — how tall is the player in world units, how far is the camera. This decides asset scale, terrain scale, and readability, and it is expensive to change later.

Pick the route (script verbs vs Rust crate) per makepad-game-director/references/architecture.md before writing code.

The simulation model

makepad-game-sim is Cx-free. Every gameplay rule you write belongs in a Cx-free crate and gets a unit test. If a rule needs a Cx to test, it is in the wrong place.

GameWorld holds entities and steps at a fixed TICK_DT. Never advance by a variable frame delta — it breaks netplay, replay, and determinism.

Movement comes in three kinds, and picking wrong is the most common design error here:

Kind	Use for	API
Mover (kinematic capsule)	players, NPCs, anything that should feel controlled	capsule_mover_step, apply_mover_contacts
Rigid body	debris, crates, ragdolls, anything that should feel thrown	RigidDynamics, step_dynamics, rigid_impulse, rigid_spin
Scripted transform	platforms, doors, lifts on rails	set position directly per tick

A player on a rigid body feels floaty and catches on geometry. A crate on a mover feels weightless. Mixed control — a mover that is sometimes rigid — is how ragdoll works (activate_ragdoll, ragdoll_active, ragdoll_body_poses), and that transition must be explicit, not emergent.

Ground and collision helpers: ground_y, ground_normal, deck_floor_under, box_floor_under, cast_ray, projectile_ccd, raycast_filter(), projectile_filter(). Use projectile_ccd for anything fast — a bullet stepped discretely tunnels through walls, and this is not a bug you will find by playing.

Also in sim: terrain, landform, water (WaterVolume, WaterWave, buoyancy), voxel, nav (NavMap, NavAgent, FlowField), decal (BulletDecal), particles, hud, player, sense, queries.

Entity lookup is O(log n) binary search over a sorted-id Vec. Do not build a parallel HashMap index beside it.

Building blocks — do not reimplement these

makepad-game-blocks already solved the hard handling problems. Reaching for raw physics when a block exists is the second most common error here.

• Car / CarConfig — vehicle handling, suspension, wheels
• Character / CharacterConfig / CharacterPose — humanoid locomotion and pose
• Plane / PlaneConfig — flight
• Npc / NpcConfig / Personality / Activity / Poi / PoiSet / DoorUse / DAY_SECONDS — daily-routine NPCs with points of interest
• Brain / BrainKind — wander, chase, patrol behaviour
• RaceKit / Checkpoint / SpawnPoint / Standing — laps, checkpoints, standings
• DriveInput, RawInput, ControlSource, PlayerRig, Seat, Blocks

Tune a *Config before writing new physics. If the config genuinely cannot express the feel, extend the block in libs/game/blocks — with a unit test — rather than bypassing it in the app.

Input

RawInput and ControlSource abstract the source; GameInputState / GamepadState come from makepad_platform::event::game_input. Support keyboard, gamepad, and touch through the same action enum — branch at the mapping layer, never inside gameplay code.

Two things that get missed and are always caught in review:

• Touch: no hover, no right-click, fat fingers. Every action needs a touch path or the mobile claim is false.
• XR: apps/arcade/src/xr_input.rs exists. If the target includes Quest, controller input is not the same shape as gamepad input.

Deadzone analog sticks, normalise diagonal keyboard movement (or diagonals are faster — the classic bug), and buffer the jump input a few frames before ground contact.

Feel

Feel is mostly timing, and timing is cheap. In rough order of return:

1. Coyote time — jump remains valid ~100 ms after leaving ground.
2. Input buffering — an action pressed just before it becomes legal still fires.
3. Acceleration curves — never set velocity directly from input for a character.
4. Camera lag and lookahead — the camera trails and leads; CameraRig in makepad-game-render owns this.
5. Hit feedback — cam_shake, a particle burst, an sfx, and a HUD flash on the same frame as the hit. All four, or the hit reads as nothing.
6. Recovery frames — a brief committed window after an action makes it feel weighty.

Script route specifics

Verbs are listed in architecture.md; makepad_game_script::api_text() is authoritative. Constraints that shape design:

• One cumulative 500k-instruction pool per tick, shared by on_tick + timers + touch events, target ≤ 2 ms. Do not write a per-entity on_tick; iterate a batch inside one handler.
• Options keys are typo-guarded. A rejected key is a wrong key.
• Use rand / rand_range, the seeded verbs — never host RNG — or netplay desyncs.
• Untrusted scripts pass through strip_capabilities with a Trust level first. AI-authored code is untrusted.

Multiplayer

makepad-game-net is host-authoritative LAN transport; makepad-game-session gives HostSession, ClientSession, Session, SessionEvent, replication, MAX_PLAYERS, and drive_input_for(world, player).

Design rules: clients send input, never state. The host steps the sim and replicates. Anything derived from std float math or unseeded RNG will desync — use makepad-game-math and seeded rng. Content replicates as (preset, seed, position), not vertex data.

makepad-game-coedit handles collaborative editing (leases, diff3, Transaction, Refusal) — a different problem from gameplay replication. Do not mix them.

Verification

cargo test -p makepad-game-sim
cargo test -p makepad-game-blocks
cargo check -p <your app crate>

Assert on behaviour, not on internals: the mover clears a 0.5 m step and does not clear a 1.5 m wall; the car's body does not sink into the road; the lap counts once per crossing and not twice; the NPC reaches its POI within N ticks. Test the composed system when the claim is about composition — a walker entering a real generated room is one test, not two half-tests that both pass while the walker floats.

Required reading

• references/core-loop.md — briefs, level structure, difficulty, state machine.
• references/physics-and-movement.md — mover vs rigid, collision, tuning tables.
• references/input-and-camera.md — action mapping, devices, camera rigs.