unity-2d-controller
Move a 2D character: platformer jump, slopes, coyote time, moving platforms, top-down movement.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- unity-2d-controller
- description
- Move a 2D character: platformer jump, slopes, coyote time, moving platforms, top-down movement.
02 资源文件 14
- 参考文档reference/facing-and-animator-bridge.md9.4 KB
- 参考文档reference/grid-step.md8.8 KB
- 参考文档reference/jump-maths.md7.6 KB
- 参考文档reference/model-choice.md8.5 KB
- 参考文档reference/platformer.md15.8 KB
- 参考文档reference/topdown-free.md9.8 KB
- 其他resources/AnimatorBridge2D.cs6.7 KB
- 其他resources/GridStepMover.cs7.3 KB
- 其他resources/MovingPlatform2D.cs2.9 KB
- 其他resources/PlatformerController2D.cs11.6 KB
- 其他resources/PlatformerMotor2D.cs15.8 KB
- 其他resources/TopDownMotor2D.cs7.3 KB
- 其他templates/PlatformerJourneyTest.cs16.2 KB
- 其他templates/TopDownJourneyTest.cs11.6 KB
03 SKILL.md 正文
unity-2d-controller — a platformer character asks physics where the ground is; it is not simulated by it
A character left to the solver is a crate with a face. A dynamic body under gravity slides down slopes, sticks to walls by friction, bounces off corners and jumps a different height every time a contact lands on the take-off step. None of those are bugs in the physics. The fix is not a setting: the character stops being simulated, decides its own velocity, and uses the engine only to ask what is in the way.
The situation → what to read
| The situation | Read |
|---|---|
Kinematic or dynamic; Rigidbody2D.Slide; who owns the transform; a second writer |
reference/model-choice.md |
| "The character slides down slopes", "it sticks to walls", "can't jump right at the edge", "falls through the moving platform": grounding, slopes, sliding downhill, one-way platforms and dropping through, moving platforms, coyote time, buffer, short hop, apex hang, dash, wall slide and wall jump, auto-run, abilities as data | reference/platformer.md |
| "The jump feels floaty": gravity and jump velocity from height and time; rise and fall gravity; why the apex is 2.85 and not 3; measuring it | reference/jump-maths.md |
| "Diagonal movement is faster": four-way, eight-way, analogue; the fast diagonal; acceleration and stopping; wall slide; twin-stick aim; screen clamp; knock-back | reference/topdown-free.md |
| One cell per step: commit then tween, key repeat, one buffered step, a refused step, pushing a pickup | reference/grid-step.md |
| "The sprite faces the wrong way": which way it faces; flipping against directional clips; the bridge that writes the Animator | reference/facing-and-animator-bridge.md |
| Reach tables, gap and ledge checks, the measuring script | unity-gameplay → reference/level-metrics.md |
| The input struct, the press latch and its buffer, a scripted driver; action assets, touch controls, rebinding | unity-input → reference/reading-input.md |
| Stick and pointer aim resolved to a direction | unity-input → reference/pointer-and-aim.md |
| Body types, simulation mode, interpolation; collider set-up, a callback that never fires | unity-physics-2d → reference/bodies-and-simulation.md |
| Casts, contact filters, a query that misses | unity-physics-2d → reference/queries-2d.md |
| Tile seams that catch the runner; composite colliders | unity-physics-2d → reference/tilemap-colliders.md |
| Platform effectors for dynamic bodies | unity-physics-2d → reference/effectors-and-joints.md |
| Which layers, and which pairs collide | unity-physics-2d → reference/layers-and-matrix.md |
| Cell coordinates on rectangular, isometric and hexagonal boards | unity-2d-grid → reference/coordinates.md |
| Occupancy, reservations, turn order, pathfinding | unity-2d-grid → reference/occupancy-and-turns.md |
| Following the runner; a camera that jitters behind it; confiners | unity-camera → reference/follow-2d.md |
| The state graph the bridge feeds, side-on | unity-animation → reference/sprite-state-graph.md |
| Directional trees fed by the facing | unity-animation → reference/blend-trees.md |
| Journeys that prove apex, coyote and buffer; recorders, situations, the probe, the never-inside invariant | unity-play-harness → reference/journeys.md |
Copy the resources/ files the model needs into a Runtime assembly beside RunInput.cs
(unity-input → resources/), and the journey from templates/ into a PlayMode test assembly
that also references the harness. The runtime files need no package — 2D physics and animation are
built-in modules; the journeys need com.unity.test-framework.
Every controller here is two halves that never mix:
RunInput ──► rules ──────────────► collision ─────────────► Rigidbody2D
(struct) PlatformerController2D PlatformerMotor2D MovePosition, once per step
what the runner wants what the level allows
coyote, cut, dash ground, slope, one-way, carry
| Half | Knows | Never knows |
|---|---|---|
Rules — resources/PlatformerController2D.cs |
Input levels and presses, timers, abilities, gravity, jump velocity | Layers, casts, normals |
Collision — resources/PlatformerMotor2D.cs |
Layers, the body's shape, what is ground, the platform under the feet | Input, gravity, what a jump is |
The rules call one method — Move(velocity, dt) — and read back four facts: Grounded,
WallSide, OnOneWay, Velocity. That seam is what lets a journey prove the jump, and lets the
collision half be replaced without touching a rule.
0. Pick the movement model
One model per character, chosen by constraint, written down before any code. If the project has
not named its view and movement model, unity-gameplay does that first.
| The game is | Model | Transform owner | Files |
|---|---|---|---|
| Side view under gravity: platformer, gated exploration, auto-runner | Kinematic body, moved to where casts allow | PlatformerMotor2D |
PlatformerMotor2D.cs, PlatformerController2D.cs, MovingPlatform2D.cs |
| Seen from above, free movement: action-adventure, twin-stick, fixed-screen shooter | Dynamic body, gravity scale 0, velocity assigned every step | The solver, from one writer | TopDownMotor2D.cs |
| Cells: tactics, tile puzzle, RPG authored to the tile | The cell map; the transform is a tween | GridStepMover |
GridStepMover.cs |
Why each, what each costs, and the grep that finds a second writer: reference/model-choice.md.
1. Start here — the side run
- Decide four numbers before the level exists: apex height 3, time to apex 0.4 s, run speed 8, coyote time 0.1 s. Gravity (37.5) and jump velocity (15) are derived, never typed in.
- Build the runner.
Rigidbody2D(Interpolate) + oneBoxCollider2D(0.8 × 1.8) +RunInputReader+PlatformerMotor2D+PlatformerController2D. The motor makes the body kinematic. Setsolidto the rooftop layer andoneWayto the platform layer — two layers, never one. - Register with the probe, where the game wires its harness:
GameProbe.SetPlayerVelocity(() => run.transform, () => (Vector3)run.Velocity);
GameProbe.Register("grounded", () => run.Grounded);
GameProbe.SetState(() => run.State); // Grounded · Rising · Falling · WallSlide · Dash
- Prove it with
templates/PlatformerJourneyTest.cs, which builds its own rooftops:
| Test | Asserts |
|---|---|
Jump_ReachesTheConfiguredApex |
A held jump peaks at apexHeight − jumpVelocity·dt/2 (2.85), within 0.05 |
Press_JustAfterTheLedge_StillJumps |
A press spent 0.08 s after the last grounded step jumps |
Press_LongAfterTheLedge_IsRefused |
A press at 0.16 s does not: coyote time is not a double jump |
Press_JustBeforeLanding_JumpsOnLanding |
With a 0.15 s buffer, a press 0.10 s before the feet touch jumps from the roof |
| all four | JourneyInvariants2D.NeverInside2D reports nothing |
- Show the gate can fail.
PLATFORMER_JOURNEY_BREAK=coyote,=bufferand=tapeach turn one test red. A journey nobody has seen fail proves nothing. - Measure the jump with
unity-gameplay→scripts/jump_report.pyagainst the timeline the first test wrote, then build the level to the number it prints.
The depot is the same loop with TopDownMotor2D and templates/TopDownJourneyTest.cs
(diagonal speed, wall slide with NeverInside2D, stopping distance); the sorting yard with
GridStepMover and two delegates.
Discipline
- One writer of the transform.
Moveis called from one place; nothing else assignstransform.position,linearVelocityor a root-motion curve on that object. Launch pads, hazards and conveyors hand a velocity to the controller (Push); they do not move the body. - Rules and collision stay in separate files. A coyote timer in the motor or a layer mask in the controller is the first step back to one file nobody can test.
- Author what the player sees. Apex height and time to apex are the tunables; gravity and jump velocity are computed. Do not use the project's gravity for the jump.
- Assign the jump, never add it.
v.y = jumpVelocity. Added to a slope's or a lift's upward velocity it is a different jump on every surface. - Velocity first, then position, gravity from the take-off step. That is the integrator the
level numbers assume; the apex sits
v0·dt/2under the designed one. Change the order and every ledge in the game moves. - Ground is a cast of the body's own shape and a normal, not a callback, a tag or a ray from the centre. And never while rising.
- Condition first, then
TryUse.canJump && input.TryUse(Launch)buffers a press; the reverse spends it in mid-air. The buffer length lives on the input source. - Read levels with
Peek, presses withTryUse, both inFixedUpdate. Never a device, and never a press rebuilt fromheld && !wasHeld. - A held jump and a tapped jump are different jumps. Measure the apex with the button held; a driver that taps is measuring the short hop.
- Clamp a move vector, do not normalise it. Clamped, a keyboard diagonal is not 41% fast and a half-pushed stick is still half speed.
- Facing comes from intent, never from velocity, and keeps its value at rest.
- In a cell game the cell is the position. It changes when the step starts; the transform catches up. Game logic that reads the transform is wrong for half of every step.
- Coyote time, buffer, apex hang and extra jumps are level-design numbers. Each changes reach; fix them before rooms are drawn and re-run the reach table when one moves.
- The human keeps the feel verdict. The journey shows the apex is 2.85 and the press was honoured at 0.08 s; whether 0.4 s to the apex feels right is a judgement.
Scope — what this skill does NOT do
| Not here | Go to |
|---|---|
| Which perspective and movement model the game has; genre recipes; reach tables | unity-gameplay |
| Tilemap layers, rooms, chunks, level data | unity-2d-level |
| Sort order, sorting from above, 2D lights | unity-2d-rendering |
| Bones, skinned sprites, swapping parts | unity-2d-animation |
| Animator graphs, blend trees, events (the bridge feeds them) | unity-animation |
| Frames into clips, pivots | unity-2d-sprites |
| Pressing use on a switch, a gate or a pickup | unity-interaction |
| Health, hurt, invincibility frames and when a hit asks for knock-back | unity-combat |
Click-to-move: on a tile board unity-2d-grid (GridPathfinder); free 2D movement unity-navigation → reference/recipes.md §9 |
|
| 3D characters and PhysX | unity-physics-3d |
Enemy behaviour, combat and interaction are not controllers: a sentry that patrols a ledge uses
PlatformerMotor2D with its own rules in place of PlatformerController2D, and what it decides
is unity-game-ai.
04 同仓库更多 Skills
unity-web-release
Ship a WebGL/WebGPU build: shrink the download, Brotli server headers, Safari and iPhone memory.
unity-vivox
Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.
unity-urp-migration
Migrate a Built-in project to URP, or fix a half-moved one: pink materials, PPv2, old shaders.
unity-ui-ugui
Canvas UI (uGUI): CanvasScaler, RectTransform anchors, Layout Groups, ScrollView, UI built from C#.
unity-ui-toolkit
UI Toolkit (UXML, USS, UIDocument): flex layout, binding, custom elements, editor windows.
unity-ugs
Unity Gaming Services API: which package, init and sign-in order, Cloud Save, Cloud Code, Remote Config.