summaryrefslogtreecommitdiff
path: root/platformer/README.md
diff options
context:
space:
mode:
authorSchark <jordan@schark.online>2026-09-23 23:09:55 -0400
committerSchark <jordan@schark.online>2026-09-23 23:09:55 -0400
commitdab65412376d1b73381446f969c1461c24169811 (patch)
tree27adfec438a9bd9f3c96a740ab54016df5f68b80 /platformer/README.md
parentaf03f388cbcff795158ea8345b5c876470229e8b (diff)
downloadgamedev-dab65412376d1b73381446f969c1461c24169811.tar.gz
gamedev-dab65412376d1b73381446f969c1461c24169811.zip
Base prompts
Diffstat (limited to '')
-rw-r--r--platformer/README.md176
1 files changed, 176 insertions, 0 deletions
diff --git a/platformer/README.md b/platformer/README.md
new file mode 100644
index 0000000..cea08bd
--- /dev/null
+++ b/platformer/README.md
@@ -0,0 +1,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