diff options
| author | Schark <jordan@schark.online> | 2026-09-23 23:09:55 -0400 |
|---|---|---|
| committer | Schark <jordan@schark.online> | 2026-09-23 23:09:55 -0400 |
| commit | dab65412376d1b73381446f969c1461c24169811 (patch) | |
| tree | 27adfec438a9bd9f3c96a740ab54016df5f68b80 /platformer/README.md | |
| parent | af03f388cbcff795158ea8345b5c876470229e8b (diff) | |
| download | gamedev-dab65412376d1b73381446f969c1461c24169811.tar.gz gamedev-dab65412376d1b73381446f969c1461c24169811.zip | |
Base prompts
Diffstat (limited to 'platformer/README.md')
| -rw-r--r-- | platformer/README.md | 176 |
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 |
