summaryrefslogtreecommitdiff
path: root/platformer/README.md
blob: cea08bd35c3793be51bb8f68709e0b57e2552d73 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
# platformer

A small 3D platformer written from scratch in C. The only libraries are GLFW, GLEW and OpenGL.

**Current scope:** a blank, flat world, one character (a box with a drop shadow), a third-person
camera, and a gamepad. That's everything. The only goal right now is to **dial in character movement**:
running, turning, jumping and falling should feel good before anything else gets built.

---

## Guiding principles

These rules apply to every change. If a change breaks one, it needs a very good reason.

1. **Minimal files.** Each file has one purpose that you can explain in a sentence (`controls.c` reads
   the gamepad, `physics.c` applies gravity and collision, and so on). If you can't say what a file
   is for, it shouldn't exist. If a file starts doing two jobs, split it.
2. **Minimal dependencies.** We build from scratch on purpose. The runtime needs GLFW (window + gamepad),
   GLEW (OpenGL function loading), OpenGL, and the C standard library, and nothing else. There are no
   math libraries, no engines and no asset pipelines. This is deliberately the opposite of UE5-style
   bloat: we should understand every line that runs each frame.
3. **Minimal scope.** Start super small and grow one piece at a time. Today it's a blank world plus
   movement. Levels, enemies, audio and the rest wait until movement feels right.
4. **Readable implementation.** Someone with ~junior gamedev knowledge should be able to read any file
   top to bottom and follow it. That means plain C99, short functions, descriptive names, a comment on
   every *why*, and no clever macros or hidden control flow.

## Inspiration: Super Mario 64

SM64 is the reference point for both **what** we build and **how** we build it.

**Scope.** Before SM64 had levels, its team spent a long time in a plain test space getting Mario's
movement and the camera to feel right. We're following the same order: the blank world *is* the
game until the controls feel great.

**Development approach.** These ideas come from SM64's design:
- **A small, purpose-built engine.** Write only what the game needs, and nothing general-purpose "just in case".
- **Fixed-rate simulation.** Game logic runs at a fixed tick rate that doesn't depend on the render
  frame rate. SM64 ran its logic at 30 Hz. We use **60 Hz** because modern displays and gamepads make
  the lower input latency noticeable, and the per-tick math stays the same either way.
- **An explicit player state machine.** SM64 has Mario "actions" (idle, walking, jumping, and so on).
  We start with four states (`IDLE`, `RUN`, `JUMP`, `FALL`) and add more only when a move requires it.
- **Analog-magnitude movement.** How far you push the stick sets how fast you move. A radial deadzone
  keeps the full 0..1 range usable.
- **Camera-relative controls.** "Up" on the stick means "away from the camera". The player orbits
  the camera with the right stick.
- **A drop shadow for depth.** A dark blob directly under the character is the most important depth
  cue in a 3D platformer, and it tells you where you'll land.

---

## Dependencies

| Library | Why | Gentoo package |
|---|---|---|
| GLFW 3.4 | window, GL context, keyboard, **gamepad** (`glfwGetGamepadState`, with built-in SDL controller mappings) | `media-libs/glfw` |
| GLEW | loads OpenGL 3.3 core functions | `media-libs/glew` |
| OpenGL 3.3 | rendering | `virtual/opengl` |
| libm | `sinf`, `cosf`, `sqrtf`, ... | (libc) |

Tools: a C99 compiler (`cc`/`gcc`/`clang`), `make`, `pkg-config`.

## Build & run

```sh
make          # build ./platformer
make run      # build and run
make debug    # -O0 -g with AddressSanitizer + UBSan
make clean
```

## Controls

The game is designed for a gamepad (Xbox-style layout names; GLFW maps other pads to it).

| Input | Action |
|---|---|
| Left stick | move (tilt amount = speed, relative to the camera) |
| Right stick | orbit camera |
| A (south button) | jump (hold longer to jump higher) |
| Back / Select | reset player to spawn |
| Start | quit |

**Keyboard fallback** (only active when no gamepad is connected, for testing): WASD = move,
arrow keys = camera, Space = jump, R = reset, Esc = quit.

---

## Architecture

| File | Purpose |
|---|---|
| `src/main.c` | Entry point. Starts every module, runs the fixed-timestep game loop, shuts down. |
| `src/config.h` | All tunable numbers in one place (speeds, gravity, camera, window). **Tune movement here.** |
| `src/math3d.h` | Tiny header-only vector/matrix math (`Vec2`, `Vec3`, `Mat4`). |
| `src/window.c/.h` | The window and OpenGL context (GLFW + GLEW), the clock, and swapping buffers. |
| `src/controls.c/.h` | Reads the gamepad (or keyboard fallback) into one abstract `Input` struct. |
| `src/world.c/.h` | The blank world: ground height and world boundaries. |
| `src/physics.c/.h` | Gravity, velocity integration and ground collision for a generic `Body`. |
| `src/player.c/.h` | The player's state machine. Turns `Input` into running, turning and jumping. |
| `src/camera.c/.h` | Third-person orbit camera that follows the player. |
| `src/render.c/.h` | Draws the ground grid, the player box and its drop shadow. Read-only. |

**Dependency direction** (arrows mean "includes / calls"; there are no cycles):

```
main ──► window, controls, world, player, camera, render
controls ──► window            (keyboard fallback needs the window handle)
player ──► physics, world, controls (Input struct only)
physics ──► world
camera ──► controls (Input struct only)
render ──► player, camera, world  (reads only, never modifies)
everything ──► config.h, math3d.h
```

**One frame:**

```
window_poll_events()
while (enough time has built up for a tick):     // fixed 60 Hz
    controls_poll()   -> Input
    player_update()   (uses Input + the camera's yaw)
    camera_update()   (follows the player's new position)
render_frame()                                   // once per display frame
window_swap()
```

**Conventions:** Y is up, right-handed coordinates. 1 unit = 1 meter. Angles are in radians.
`dt` is in seconds. Public functions are named `module_verb` (`player_update`, `camera_yaw`).
A module keeps its private state in `static` variables inside its `.c` file, and there are no
cross-file globals.

---

## Scaffolding workflow (current stage)

Right now the files contain **prompts, not code**. Each file opens with a comment block made of these sections:

- `PURPOSE`
- `FITS IN`
- `INTERFACE` (headers) or `IMPLEMENT` (sources)
- `CONVENTIONS`
- `NOT IN SCOPE`
- `DONE WHEN`

An implementing agent (or person) fills in each file from its prompt.

Rules for filling in:
1. **Follow the interfaces in the headers exactly.** The names, struct fields and signatures are shared
   across files, so changing one breaks the others. If an interface truly has to change, update
   every prompt that mentions it.
2. **Keep the prompt block** at the top of each file. It becomes that file's documentation.
3. Respect `NOT IN SCOPE`. Leave it out, even when it's tempting to add.

Suggested fill-in order (each step can be compiled before moving on):

1. `config.h`, `math3d.h`
2. `window.c/.h`
3. `controls.c/.h`
4. `world.c/.h`
5. `physics.c/.h`
6. `camera.c/.h`
7. `player.c/.h`
8. `render.c/.h`
9. `main.c`
10. `Makefile`

## Roadmap (explicitly *not* now)

- Collision with real geometry (platforms, walls, slopes)
- Loading levels
- SM64-style extra moves: double/triple jump, long jump, wall kick, ground pound
- Character model and animation
- Audio
- On-screen text/HUD
- Interpolating render state between ticks