
script a platformer character with gravity, jumping and collision in Godot 4, scale and crop its sprite to fit the level, and use the physics of motion to predict and then tune its jump height.
Instruction
Platformers are a physics lesson in disguise. When a character jumps, the game is simulating a body launched upward and pulled back down by gravity, one frame at a time. Knowing the physics lets you design a jump instead of guessing at one. (Adapted from the Godot documentation’s “Using CharacterBody2D” and “2D movement overview”, CC BY 3.0.)
Collision needs shapes. Physics bodies collide through CollisionShape2D children. Godot has several body types. A StaticBody2D never moves (floors, walls). A RigidBody2D is moved by the physics engine (a crate you can push). A CharacterBody2D is moved by your code but still stops at walls and floors. Your character is a CharacterBody2D; the ground is a StaticBody2D with a wide rectangle shape.
Fitting the sprite: scale and crop. Downloaded art rarely arrives at the size your level needs. Many Kenney characters are drawn at 128 × 128 pixels, but this test room is built from 32-pixel steps. Select the Sprite2D and set its scale in the Inspector: a scale of (0.5, 0.5) shows a 128-pixel image at 64 × 64, two steps tall; (0.25, 0.25) shows it at 32 × 32. Keep x and y equal so the art is not stretched. If your image is a sheet holding several drawings, crop out just one: turn on region_enabled and set region_rect to the rectangle you want, for example x 0, y 0, width 32, height 32 for the top-left 32-pixel drawing. The Godot class reference describes region_enabled as cutting the texture from a larger atlas. Fit the CollisionShape2D to the sprite after scaling, or the character will collide with an invisible box larger or smaller than what the player sees.
Input actions. Rather than checking specific keys, define named actions in Project Settings > Input Map: move_left, move_right and jump, each with a key and a gamepad button. Named actions make remapping controls possible later, which matters for accessibility.
extends CharacterBody2D
@export var speed: float = 220.0
@export var jump_velocity: float = -420.0
@export var gravity: float = 980.0
func _physics_process(delta: float) -> void:
if not is_on_floor():
velocity.y += gravity * delta
if Input.is_action_just_pressed("jump") and is_on_floor():
velocity.y = jump_velocity
var direction := Input.get_axis("move_left", "move_right")
velocity.x = direction * speed
move_and_slide()Walk through it. If the character is in the air, gravity adds 980 pixels per second to its downward speed every second. If the jump button was just pressed this frame and the character is standing, its vertical velocity is set to −420 (negative is up). Input.get_axis returns −1, 0 or 1 (or a value in between on an analog stick). Then move_and_slide() moves the body and stops it at anything solid; after the move, is_on_floor() knows whether it landed.
Predicting the jump. With launch speed v and gravity g, the character rises until its vertical speed reaches zero. That takes t = v ÷ g = 420 ÷ 980 ≈ 0.43 s. The peak height is h = v2 ÷ (2g) = 4202 ÷ 1960 = 176,400 ÷ 1960 = 90 pixels. The whole jump lasts twice the rise time, about 0.86 s, so at 220 px/s the character travels about 220 × 0.86 ≈ 189 pixels sideways. Because the engine updates in steps, 60 times a second, the real peak comes out a few pixels higher (about 93 px); the formula is a designer’s estimate, and you measure to confirm.
Designing backward. Suppose your level has ledges 64 pixels high and you want the character to clear them with a little room, say a 100-pixel jump. Rearranging, v = √(2gh) = √(2 × 980 × 100) = √196,000 ≈ 443 px/s. Set jump_velocity to −443 and test. Doubling gravity while keeping the height makes a snappier, heavier jump; that is a feel decision you can now make on purpose.
Safety and care of files. Long debugging sessions invite bad posture and lost work. Take the 20-20-20 break, keep drinks away from keyboards, and back up the project folder before any big change so you can always return to a version that worked.
📖 Read for this lesson
The reading opens over the lesson; close it to come back to exactly where you were. The checks below draw on it.
Build: Platformer character and jump test room
Question. Does the jump height predicted by h = v² ÷ (2g) match what the character actually does in Godot, and can you tune the character to clear a ledge of a chosen height?
Materials
- A computer with the Godot 4 desktop editor (4.3 or later)
- A Kenney character sprite and one tile or block sprite (CC0, downloaded from kenney.nl with no account), or icon.svg
- A ruler-marker scene: a Line2D or a stack of 32-pixel blocks to read heights against
- A calculator and your build log
- Keep the ergonomic set-up and 20-20-20 breaks; stand and stretch between the two sessions.
- Keep drinks away from keyboards and cables tidy.
- Duplicate the project folder with a dated name before changing physics values, so you can return to a working version.
Procedure
- In Project Settings > Input Map add the actions move_left, move_right and jump, and assign keys (and a gamepad button if you have one).
- Make Player.tscn: CharacterBody2D root, Sprite2D, and CollisionShape2D with a CapsuleShape2D or RectangleShape2D. Scale the Sprite2D so the character is two 32-pixel steps tall (for a 128-pixel image, scale 0.5); if your art is a sheet, enable region and set region_rect to crop one drawing. Then fit the collision shape to the scaled sprite, attach and type the script.
- Make TestRoom.tscn: a Node2D root with a StaticBody2D floor (a wide RectangleShape2D plus a sprite or ColorRect so you can see it), two ledges of different heights, and a height marker made of labeled 32-pixel steps beside the start point. Instance the player and run.
- Compute the predicted peak height for the starting values, jump ten times beside the marker and record the peak you observe. (Optional precision: add print(global_position.y) in the script and read the lowest value in the Output panel.)
- Choose a target height that clears your higher ledge with a margin, compute the jump_velocity needed, set it in the Inspector and test it.
- Try one feel change, doubling gravity and recomputing jump_velocity for the same height, and describe the difference in your build log.
Data
| Trial | gravity (px/s²) | jump_velocity (px/s) | Predicted height v²/2g (px) | Observed height (px) | Clears ledge? |
|---|---|---|---|---|---|
| Start | 980 | −420 | 90 | ||
| Tuned | 980 | ||||
| Heavy | 1960 | ||||
| Sprite fitting: image size ____ × ____ px; scale ____; region_rect (if used) ____; size on screen ____ × ____ px | |||||
Analysis
- How close was the observed height to the prediction? Give a reason for any difference (frame stepping, reading the marker, sprite size).
- Show the calculation you used to choose your tuned jump_velocity, and state whether it worked.
- How did doubling gravity change the feel of the jump at the same height, and what kind of game would suit each version?
If you cannot do this build in person: Without Godot, run the same calculations, then build a frame-by-frame table in a free spreadsheet: start with velocity −420 and height 0, and each row add 980/60 to velocity and velocity/60 to height. Find the row where velocity changes sign and compare that height with the formula.
Formative check
Work through these before moving on. They are not graded — they tell you whether the standard below has landed yet.
With gravity 980 px/s² and jump_velocity −490 px/s, the rise time is 490 ÷ 980 = s and the peak height is 490² ÷ 1960 = px.
Which body type should a floor use?
You double gravity to 1960 and leave jump_velocity at -420. What happens to the jump height?
Missouri standard: MM.IMG.6
Your character image is 128 × 128 pixels, and you want it two 32-pixel steps (64 pixels) tall without distortion. What should you set?
How confident are you that you can script gravity, jumping and collision and use physics to tune a jump?
Practice
Work these on paper or in your notebook, then open Check your answer. Aim for all of Fluency and Application; try at least one Challenge.
Printable version: this unit’s practice workbook (PDF)
Fluency
Build speed and accuracy with the core skill.
- Name the body type: (a) a floor; (b) a crate the physics engine pushes around; (c) a character moved by your code that stops at walls.
Check your answer
Answer: (a) StaticBody2D; (b) RigidBody2D; (c) CharacterBody2D.All three collide through CollisionShape2D children. - What values can Input.get_axis(“move_left”, “move_right”) return on a keyboard, and why does the lesson use named actions instead of checking keys directly?
Check your answer
Answer: −1 (left), 0 (neither or both) or 1 (right); an analog stick can give values in between. Named actions in the Input Map make remapping controls possible, which matters for accessibility.Each action can have a key and a gamepad button. - A character image is 128 × 128 pixels and your level is built from 32-pixel steps. What scale shows it one step tall? What scale shows it two steps tall?
Check your answer
Answer: One step: scale (0.25, 0.25). Two steps: scale (0.5, 0.5).32 ÷ 128 = 0.25 and 64 ÷ 128 = 0.5. Keep x and y equal so the art is not stretched, then refit the collision shape.
Application
Use the skill in context. Show your reasoning.
- With gravity 980 px/s² and jump_velocity −350 px/s, find the rise time and the predicted peak height.
Check your answer
Answer: Rise time ≈ 0.36 s; peak height = 62.5 px.t = v ÷ g = 350 ÷ 980 ≈ 0.357 s. h = v² ÷ (2g) = 122,500 ÷ 1960 = 62.5 px. - Your ledge is four 32-pixel steps tall (128 px). With gravity 980, what jump_velocity reaches exactly 128 px? Round to the nearest whole number.
Check your answer
Answer: About −501 px/s.v = √(2gh) = √(2 × 980 × 128) = √250,880 ≈ 500.9, so set jump_velocity to about −501 (negative is up). In practice add a margin so it clears the ledge. - With gravity 980, jump_velocity −420 and speed 300 px/s, the jump lasts about 0.86 s. How far does the character travel sideways during one jump?
Check your answer
Answer: About 257 px.Rise time 420 ÷ 980 ≈ 0.43 s, so the whole jump is about 0.857 s. 300 × 0.857 ≈ 257 px. - Find the bug. A student sets @export var jump_velocity: float = 420.0 and the character never leaves the ground. Why, and what is the fix?
Check your answer
Answer: In Godot 2D, negative y is up. A positive 420 pushes the character down into the floor. Use −420.0.The script sets velocity.y = jump_velocity when jump is pressed on the floor, so the sign decides the direction. - A sprite sheet has a row of 32 × 32 drawings. What region_rect crops out the second drawing from the left in the top row?
Check your answer
Answer: x 32, y 0, width 32, height 32.The first drawing starts at x 0, so the second starts one drawing-width later, at x 32. Turn on region_enabled first.
Challenge
Stretch problems. Expect to think before you write.
- You double gravity to 1960 but want the jump to stay 100 px high. What jump_velocity do you need, and how will the jump feel compared with gravity 980?
Check your answer
Answer: About −626 px/s. It will feel snappier and heavier: a quicker rise and fall to the same height.v = √(2 × 1960 × 100) = √392,000 ≈ 626.1. The rise time drops from √(2 × 100 ÷ 980) ≈ 0.45 s to 626 ÷ 1960 ≈ 0.32 s.
Review
Keep earlier skills sharp.
- Review (Lesson 2.3): what is the probability of rolling a sum of 7 with two six-sided dice, and why?
Check your answer
Answer: 6/36 = 1/6, about 17%.7 happens 6 ways: 1+6, 2+5, 3+4, 4+3, 5+2, 6+1, out of 36 equally likely outcomes.
Platformer Jump: Formulas, a Frame-by-Frame Table and Predicted-Versus-Measured Values
SLS original; values computed by SLS and cross-checked in Godot 4.7.2 · SLS original
Why this reading. The lab asks you to predict a jump height from gravity and launch speed, then compare it with what you measure. This sheet works the examples with the exact code from the lesson so your predicted and measured columns can be checked against a known-good result.
Formulas
Rise time t = v ÷ g. Peak height h = v² ÷ (2g). To design backward: v = √(2gh).
Frame by frame: jump_velocity −420, gravity 980, 60 fps
Each physics frame adds 980 ÷ 60 = 16.33 to the downward speed, then the body moves by speed ÷ 60. Frame 0 is the frame the jump button is pressed.
| Frame | Vertical speed (px/s, negative is up) | Height above start (px) |
|---|---|---|
| 0 | -420.0 | 7.0 |
| 1 | -403.7 | 13.7 |
| 2 | -387.3 | 20.2 |
| 3 | -371.0 | 26.4 |
| 4 | -354.7 | 32.3 |
| 5 | -338.3 | 37.9 |
| 6 | -322.0 | 43.3 |
| 7 | -305.7 | 48.4 |
The peak comes on frame 25 (0.42 s) at 93.5 px, and the character is back at the floor by frame 52, about 0.87 s after the press. Sideways at 220 px/s that is about 220 × 0.87 = 191 pixels.
Predicted against a 60 fps measurement
| Jump speed | Gravity | Predicted peak (px) | Measured at 60 fps (px) | Rise time predicted | Frame of peak, in seconds |
|---|---|---|---|---|---|
| 420 | 980 | 90.0 | 93.5 | 0.43 s | 0.42 s |
| 490 | 980 | 122.5 | 126.6 | 0.50 s | 0.48 s |
| 443 | 980 | 100.1 | 103.8 | 0.45 s | 0.45 s |
The measured height is a few pixels above the formula every time. The gap is about v ÷ 120: for 420 that is 3.5, for 490 it is 4.1. It comes from the engine moving in 60 discrete steps rather than smoothly, so use the formula to design and measure to confirm.
Doubling gravity
| Jump speed | Gravity | Predicted | Measured at 60 fps |
|---|---|---|---|
| 420 | 1960 | 45.0 px | 48.5 px |
| 594 | 1960 | 90.0 px | 95.0 px |
The lesson’s rule works: doubling gravity halves the height, and keeping a 90-pixel jump needs v = √(2 × 1960 × 90) = 594.
Your data table (template)
| Trial | Jump speed | Gravity | Predicted (px) | Measured (px) | Difference |
|---|---|---|---|---|---|
| 1 | 420 | 980 | 90.0 | ||
| 2 | 490 | 980 | 122.5 |
Your measured values should land within a few pixels of the measured column above (93.5 px for 420; 126.6 px for 490). Measure by reading the character’s y position at the start and at the highest point.
A ledge 64 pixels high is cleared by 90 − 64 = 26 pixels of room.