From dab65412376d1b73381446f969c1461c24169811 Mon Sep 17 00:00:00 2001 From: Schark Date: Wed, 23 Sep 2026 23:09:55 -0400 Subject: Base prompts --- platformer/.gitignore | 3 + platformer/README.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++ platformer/src/camera.c | 51 ++++++++++++++ platformer/src/camera.h | 52 ++++++++++++++ platformer/src/config.h | 84 ++++++++++++++++++++++ platformer/src/controls.c | 75 ++++++++++++++++++++ platformer/src/controls.h | 46 ++++++++++++ platformer/src/main.c | 67 ++++++++++++++++++ platformer/src/math3d.h | 77 ++++++++++++++++++++ platformer/src/physics.c | 40 +++++++++++ platformer/src/physics.h | 36 ++++++++++ platformer/src/player.c | 73 +++++++++++++++++++ platformer/src/player.h | 48 +++++++++++++ platformer/src/render.c | 65 +++++++++++++++++ platformer/src/render.h | 31 ++++++++ platformer/src/window.c | 44 ++++++++++++ platformer/src/window.h | 43 +++++++++++ platformer/src/world.c | 29 ++++++++ platformer/src/world.h | 40 +++++++++++ 19 files changed, 1080 insertions(+) create mode 100644 platformer/.gitignore create mode 100644 platformer/README.md create mode 100644 platformer/src/camera.c create mode 100644 platformer/src/camera.h create mode 100644 platformer/src/config.h create mode 100644 platformer/src/controls.c create mode 100644 platformer/src/controls.h create mode 100644 platformer/src/main.c create mode 100644 platformer/src/math3d.h create mode 100644 platformer/src/physics.c create mode 100644 platformer/src/physics.h create mode 100644 platformer/src/player.c create mode 100644 platformer/src/player.h create mode 100644 platformer/src/render.c create mode 100644 platformer/src/render.h create mode 100644 platformer/src/window.c create mode 100644 platformer/src/window.h create mode 100644 platformer/src/world.c create mode 100644 platformer/src/world.h (limited to 'platformer') diff --git a/platformer/.gitignore b/platformer/.gitignore new file mode 100644 index 0000000..a64aa5d --- /dev/null +++ b/platformer/.gitignore @@ -0,0 +1,3 @@ +# Build output +/build/ +/platformer 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 diff --git a/platformer/src/camera.c b/platformer/src/camera.c new file mode 100644 index 0000000..00f8d4a --- /dev/null +++ b/platformer/src/camera.c @@ -0,0 +1,51 @@ +/* + * ============================================================ + * FILE: camera.c + * + * PURPOSE: A player-controlled third-person orbit camera, in the spirit of + * SM64's "Lakitu" camera but much simpler. A good camera matters as + * much for movement feel as the movement code itself. + * + * FITS IN: Implements camera.h. Reads Input.look (controls.h) and the + * player's position (passed in by main.c). Produces matrices for + * render.c and a yaw for player.c. + * + * IMPLEMENT: + * - camera_init(c, follow_point): + * target = follow_point + (0, CAMERA_TARGET_HEIGHT, 0) (snap, no smoothing) + * yaw = 0 (camera sits on +Z looking toward -Z) + * pitch = CAMERA_PITCH_DEFAULT + * distance = CAMERA_DISTANCE + * compute position. + * + * - camera_update(c, in, follow_point, dt): + * 1. Orbit: yaw += in->look.x * CAMERA_YAW_SPEED * dt + * pitch += in->look.y * CAMERA_PITCH_SPEED * dt + * Clamp pitch to [CAMERA_PITCH_MIN, CAMERA_PITCH_MAX], wrap yaw with + * wrap_angle(). Check the sign by feel: pushing the right stick RIGHT + * should swing the camera so the view turns right (the camera moves + * left around the player). Flip the sign if it feels backwards and + * leave a comment. + * 2. Follow: move target toward (follow_point + target height) with + * frame-rate-independent exponential smoothing: + * t = 1 - expf(-CAMERA_FOLLOW_RATE * dt) + * target = vec3_lerp(target, desired, t) + * Comment WHY: a camera that snaps rigidly to the player looks jittery, + * and a little lag lets you see the motion. + * 3. Recompute position with the YAW CONVENTION in camera.h. + * + * - camera_yaw(): return c->yaw. + * - camera_view(): mat4_look_at(position, target, (0,1,0)). + * - camera_projection(c, aspect): mat4_perspective(CAMERA_FOV_DEG converted to + * radians, aspect, CAMERA_NEAR, CAMERA_FAR). + * + * CONVENTIONS: Radians internally; FOV converted once from degrees. + * + * NOT IN SCOPE: Camera collision, auto-recenter, shake, look-ahead. + * (Good candidates for later tuning, not for now.) + * + * DONE WHEN: The right stick orbits smoothly all the way around the player, + * pitch stops at its limits, and the camera trails the running + * player slightly without jitter. + * ============================================================ + */ diff --git a/platformer/src/camera.h b/platformer/src/camera.h new file mode 100644 index 0000000..ead4bc9 --- /dev/null +++ b/platformer/src/camera.h @@ -0,0 +1,52 @@ +/* + * ============================================================ + * FILE: camera.h + * + * PURPOSE: Public interface for the third-person orbit camera: it sits + * on a sphere around the player and the right stick moves it + * around that sphere. + * + * FITS IN: main.c calls camera_update() each tick AFTER player_update(). + * player_update() receives camera_yaw() so "stick up" means "away + * from the camera". render.c reads camera_view()/camera_projection(). + * + * INTERFACE: Use these exact names: + * + * typedef struct Camera { + * Vec3 target; the smoothed point we look at (near the player) + * float yaw; orbit angle around the target, radians + * float pitch; angle above horizontal, radians + * float distance; meters from target + * Vec3 position; derived eye position (recomputed in camera_update) + * } Camera; + * + * void camera_init(Camera *c, Vec3 follow_point); + * void camera_update(Camera *c, const Input *in, Vec3 follow_point, float dt); + * follow_point = the player's feet position; the camera adds + * CAMERA_TARGET_HEIGHT itself. + * float camera_yaw(const Camera *c); + * Mat4 camera_view(const Camera *c); + * Mat4 camera_projection(const Camera *c, float aspect); + * + * YAW CONVENTION (player.c relies on this, so keep it exact): + * position = target + distance * ( sin(yaw)*cos(pitch), + * sin(pitch), + * cos(yaw)*cos(pitch) ) + * So on the ground plane, the camera's + * forward (toward target) = (-sin(yaw), 0, -cos(yaw)) + * right = ( cos(yaw), 0, -sin(yaw)) + * + * Include "math3d.h" and "controls.h". + * + * CONVENTIONS: Include guard: CAMERA_H. + * + * NOT IN SCOPE: Collision with geometry, automatic "behind the player" + * recentering, cutscene/fixed cameras, zoom levels. + * + * DONE WHEN: player.c and render.c can be written against this header alone. + * ============================================================ + */ +#ifndef CAMERA_H +#define CAMERA_H + +#endif /* CAMERA_H */ diff --git a/platformer/src/config.h b/platformer/src/config.h new file mode 100644 index 0000000..1aa6447 --- /dev/null +++ b/platformer/src/config.h @@ -0,0 +1,84 @@ +/* + * ============================================================ + * FILE: config.h + * + * PURPOSE: Every tunable number in the game, in one place. When movement + * "feels wrong", this is the first (and usually only) file to edit. + * + * FITS IN: Included by almost every .c file. Contains only #defines, + * with no functions, no types and no includes. + * Nothing in the game should hard-code a number that appears here. + * + * INTERFACE: Plain #define constants, float literals with an `f` suffix. + * Give EVERY constant a one-line comment that says what it + * changes about the *feel*, e.g. "higher = snappier stops". + * Use these exact names (other files depend on them). The + * values are starting points for tuning: + * + * Window + * WINDOW_WIDTH 1280 + * WINDOW_HEIGHT 720 + * WINDOW_TITLE "platformer" + * SKY_COLOR_R/G/B 0.45f 0.65f 0.90f (clear color) + * + * Simulation timing + * TICK_HZ 60 (fixed logic rate; SM64 used 30) + * TICK_DT (1.0f / TICK_HZ) (seconds per tick) + * MAX_FRAME_TIME 0.25f (clamp to avoid a "spiral of death" + * after a stall / breakpoint) + * + * Input + * MOVE_DEADZONE 0.20f (radial, left stick) + * LOOK_DEADZONE 0.20f (radial, right stick) + * + * Player: ground movement + * PLAYER_MAX_SPEED 9.0f m/s at full stick tilt + * PLAYER_GROUND_ACCEL 30.0f m/s^2 speeding up toward target speed + * PLAYER_GROUND_FRICTION 40.0f m/s^2 slowing down with no input + * PLAYER_TURN_RATE 12.0f rad/s max facing rotation on ground + * + * Player: air movement + * PLAYER_AIR_CONTROL 0.30f 0..1 multiplier on accel + turn rate in air + * PLAYER_JUMP_VELOCITY 14.0f m/s upward at jump start (~2.4 m apex) + * PLAYER_JUMP_CUT 0.50f vel.y multiplier when A released while rising + * + * Physics + * GRAVITY 40.0f m/s^2 (stronger than real 9.8 on purpose: + * platformers feel floaty with real gravity) + * TERMINAL_VELOCITY 50.0f m/s max fall speed + * + * Player: size (used by render, and later by collision) + * PLAYER_HALF_WIDTH 0.4f m + * PLAYER_HEIGHT 1.6f m (body.pos is the player's FEET) + * + * Camera + * CAMERA_DISTANCE 10.0f m from target + * CAMERA_TARGET_HEIGHT 1.0f m above player's feet to look at + * CAMERA_PITCH_DEFAULT 0.35f rad above horizontal + * CAMERA_PITCH_MIN 0.05f rad + * CAMERA_PITCH_MAX 1.20f rad + * CAMERA_YAW_SPEED 2.5f rad/s at full right-stick tilt + * CAMERA_PITCH_SPEED 1.5f rad/s at full right-stick tilt + * CAMERA_FOLLOW_RATE 8.0f 1/s; higher = camera catches up faster + * CAMERA_FOV_DEG 60.0f vertical field of view + * CAMERA_NEAR 0.1f + * CAMERA_FAR 500.0f + * + * World + * WORLD_HALF_EXTENT 100.0f m; the ground is a square of 2x this per side + * GRID_SPACING 1.0f m between grid lines + * GRID_MAJOR_EVERY 10 every Nth line drawn brighter + * + * CONVENTIONS: 1 unit = 1 meter, seconds, radians (degrees only for the FOV, + * converted where it's used). Include guard: CONFIG_H. + * + * NOT IN SCOPE: Runtime config files, command-line parsing, hot-reload. + * + * DONE WHEN: Every constant above exists with a comment, and no other + * file contains a magic number for any of these concepts. + * ============================================================ + */ +#ifndef CONFIG_H +#define CONFIG_H + +#endif /* CONFIG_H */ diff --git a/platformer/src/controls.c b/platformer/src/controls.c new file mode 100644 index 0000000..850a1ae --- /dev/null +++ b/platformer/src/controls.c @@ -0,0 +1,75 @@ +/* + * ============================================================ + * FILE: controls.c + * + * PURPOSE: Turns the physical gamepad (primary) or keyboard (fallback) + * into the abstract Input struct from controls.h. Getting + * the analog feel right here (the deadzone and stick scaling) + * matters as much as the player code for movement feel. + * + * FITS IN: main.c calls controls_poll() once per fixed tick. It uses + * GLFW's gamepad API directly and window_handle() (window.h) + * only for keyboard reads. It's the only file that reads raw + * input devices. + * + * IMPLEMENT: + * - Private state: the previous tick's button states (for the "pressed" + * edges), e.g. `static bool s_prev_jump, s_prev_reset, s_prev_quit;` + * + * - Finding a gamepad (keep it simple; this also handles hot-plugging): + * each poll, loop GLFW_JOYSTICK_1..GLFW_JOYSTICK_LAST and use the first + * jid where glfwJoystickIsGamepad(jid) is true, then read it with + * glfwGetGamepadState(jid, &state). GLFW 3.4 has SDL's controller + * mapping database built in, so Xbox/PlayStation/Switch pads all show + * up in the standard layout. Print a line to stdout when the active + * pad connects or disconnects (glfwGetGamepadName), so it's clear + * which device is in use. + * + * - Gamepad mapping: + * move.x = GLFW_GAMEPAD_AXIS_LEFT_X + * move.y = -GLFW_GAMEPAD_AXIS_LEFT_Y (GLFW reports up as NEGATIVE, + * so flip it: up = forward = +y) + * look.x = GLFW_GAMEPAD_AXIS_RIGHT_X + * look.y = -GLFW_GAMEPAD_AXIS_RIGHT_Y + * jump = GLFW_GAMEPAD_BUTTON_A + * reset = GLFW_GAMEPAD_BUTTON_BACK + * quit = GLFW_GAMEPAD_BUTTON_START + * + * - RADIAL deadzone (write a small static helper, used for both sticks): + * len = length of the raw (x, y) + * if len < deadzone -> (0, 0) + * else rescale so the edge of the deadzone maps to 0 and full tilt maps + * to 1: new_len = (len - deadzone) / (1 - deadzone), clamped to 1, + * keeping the original direction. + * WHY radial and not per-axis: a per-axis deadzone snaps diagonals + * to the cardinal directions and makes slow walking feel "sticky". SM64 + * also computes one magnitude from the whole stick and uses it for speed. + * Also clamp the final length to 1, because some pads report corners past 1. + * Use MOVE_DEADZONE / LOOK_DEADZONE from config.h. + * + * - Keyboard fallback, used ONLY when no gamepad is connected: + * W/S/A/D -> move (normalize diagonals so the length is <= 1) + * Arrow keys -> look + * Space -> jump, R -> reset, Esc -> quit + * Read keys with glfwGetKey(window_handle(), key). + * Esc also quits when a gamepad IS connected (so you can always exit). + * + * - Edge detection: pressed = down_now && !down_last_tick. Then store + * down_now for next tick. + * + * - Zero the whole Input at the start of controls_poll so no stale data leaks. + * + * CONVENTIONS: `s_` prefix for statics. is included here (not + * in controls.h). + * + * NOT IN SCOPE: Rebinding, loading an external gamecontrollerdb.txt, + * rumble, triggers/shoulder buttons (add them when a move needs + * them), input recording/replay. + * + * DONE WHEN: With a pad: a small stick tilt gives a small |move|, full + * tilt gives ~1.0, the resting stick gives exactly (0, 0), and each + * A press sets jump_pressed for exactly one tick. Unplugging the + * pad switches to the keyboard without a crash, and plugging it back + * in switches back. + * ============================================================ + */ diff --git a/platformer/src/controls.h b/platformer/src/controls.h new file mode 100644 index 0000000..dbbe936 --- /dev/null +++ b/platformer/src/controls.h @@ -0,0 +1,46 @@ +/* + * ============================================================ + * FILE: controls.h + * + * PURPOSE: Defines `Input`, the one abstract snapshot of what the player + * is asking for this tick. Gameplay code reads Input and never + * reads a raw device, so the player and camera don't care whether + * a gamepad or the keyboard produced it. + * + * FITS IN: main.c calls controls_poll() once per fixed tick and passes the + * Input to player_update() and camera_update(). + * + * INTERFACE: Use these exact names: + * + * typedef struct Input { + * Vec2 move; left stick after the deadzone. Length is 0..1. + * +x = right, +y = FORWARD (stick pushed up). + * Vec2 look; right stick after the deadzone. Length is 0..1. + * +x = orbit camera right, +y = tilt camera up. + * bool jump_held; A is down this tick + * bool jump_pressed; A went down THIS tick (true for one tick only) + * bool reset_pressed; Back/Select went down this tick (one tick only) + * bool quit_pressed; Start (or Esc) went down this tick (one tick only) + * bool using_gamepad; true if a gamepad produced this Input (debug info) + * } Input; + * + * void controls_init(void); call after window_init() + * void controls_poll(Input *out); call once per FIXED TICK (not once per + * frame). The "pressed" edges are + * worked out tick-to-tick, so a press + * is never lost or counted twice. + * + * Include and "math3d.h" (for Vec2). + * + * CONVENTIONS: Include guard: CONTROLS_H. + * + * NOT IN SCOPE: Rebinding, multiple players, mouse look, rumble. + * + * DONE WHEN: player.c and camera.c can be written against Input alone, + * without including GLFW. + * ============================================================ + */ +#ifndef CONTROLS_H +#define CONTROLS_H + +#endif /* CONTROLS_H */ diff --git a/platformer/src/main.c b/platformer/src/main.c new file mode 100644 index 0000000..4e9e07a --- /dev/null +++ b/platformer/src/main.c @@ -0,0 +1,67 @@ +/* + * ============================================================ + * FILE: main.c + * + * PURPOSE: Entry point. Starts every module, runs the game loop, and shuts + * everything down. It should read like a table of contents for the + * game, with NO gameplay logic of its own. + * + * FITS IN: The top of the dependency graph. Includes window.h, controls.h, + * world.h, player.h, camera.h, render.h, config.h. + * + * IMPLEMENT: + * - Startup (in this order, and if any step fails, clean up what + * already started and return 1): + * window_init() -> controls_init() -> world_init() + * player_init(&player, world_spawn_point()) + * camera_init(&camera, player.body.pos) + * render_init() + * + * - Game loop with a FIXED TIMESTEP + accumulator (explain it in a comment; + * this is the most important idea in the file): + * + * previous = window_time(); accumulator = 0; + * while (!window_should_close()): + * now = window_time(); + * frame_time = now - previous; previous = now; + * if frame_time > MAX_FRAME_TIME: frame_time = MAX_FRAME_TIME + * accumulator += frame_time; + * + * window_poll_events(); + * + * while accumulator >= TICK_DT: // 0, 1 or several ticks + * controls_poll(&input); + * if input.quit_pressed: window_request_close(); + * if input.reset_pressed: player_reset(&player, world_spawn_point()); + * player_update(&player, &input, camera_yaw(&camera), TICK_DT); + * camera_update(&camera, &input, player.body.pos, TICK_DT); + * accumulator -= TICK_DT; + * + * render_frame(&camera, &player, window_aspect()); + * window_swap(); + * + * WHY the fixed timestep: the game behaves the same (identical jump + * height, identical speeds) no matter the monitor's refresh rate or a + * dropped frame, which is exactly what you need when tuning movement. SM64 + * ran logic at 30 Hz; we use TICK_HZ (60). + * WHY player before camera: the camera then follows where the player IS, + * not where it was a tick ago. SM64 updates Mario before the camera too. + * + * - Debug readout for tuning (a few times per second, not every frame): + * window_set_title() with something like + * "platformer | RUN | speed 7.42 m/s | y 1.83 | pad" + * using player_state_name(), forward_speed, body.pos.y and + * input.using_gamepad. This is our "HUD" until text rendering exists. + * + * - Shutdown in reverse order: render_shutdown() -> window_shutdown(). + * + * CONVENTIONS: `int main(void)`. Game objects (Player, Camera, Input) are + * local variables in main, passed by pointer. No globals. + * + * NOT IN SCOPE: Menus, pause, command-line args, state interpolation. + * + * DONE WHEN: `make run` opens the window. The player can run, turn and jump + * with a gamepad, the camera orbits, Back resets, Start quits, and + * the title bar shows live state/speed. + * ============================================================ + */ diff --git a/platformer/src/math3d.h b/platformer/src/math3d.h new file mode 100644 index 0000000..316e418 --- /dev/null +++ b/platformer/src/math3d.h @@ -0,0 +1,77 @@ +/* + * ============================================================ + * FILE: math3d.h + * + * PURPOSE: The small amount of vector/matrix math the game needs, written + * by hand so we don't pull in a math library. + * + * FITS IN: Header-only (every function is `static inline`). Included by + * any file that does math. Depends only on . + * + * INTERFACE: Use these exact names: + * + * Constants + * M3D_PI 3.14159265358979f (C99 doesn't guarantee M_PI) + * + * Types (plain structs, passed and returned BY VALUE since they're small) + * typedef struct { float x, y; } Vec2; + * typedef struct { float x, y, z; } Vec3; + * typedef struct { float m[16]; } Mat4; COLUMN-MAJOR, element (row r, + * col c) is m[c*4 + r], so it can + * go straight to glUniformMatrix4fv + * with transpose = GL_FALSE. + * + * Scalar helpers + * float clampf(float v, float lo, float hi); + * float approachf(float current, float target, float max_step); + * moves current toward target by at most max_step, never overshoots. + * (Used for acceleration/friction.) + * float wrap_angle(float a); + * returns a in (-PI, PI]. + * float approach_angle(float current, float target, float max_step); + * like approachf but takes the SHORT way around the circle. + * (Used for turning the player.) + * + * Vec2 + * Vec2 vec2_make(float x, float y); + * float vec2_length(Vec2 v); + * + * Vec3 + * Vec3 vec3_make(float x, float y, float z); + * Vec3 vec3_add(Vec3 a, Vec3 b); + * Vec3 vec3_sub(Vec3 a, Vec3 b); + * Vec3 vec3_scale(Vec3 v, float s); + * float vec3_dot(Vec3 a, Vec3 b); + * Vec3 vec3_cross(Vec3 a, Vec3 b); + * float vec3_length(Vec3 v); + * Vec3 vec3_normalize(Vec3 v); returns (0,0,0) for zero-length input + * Vec3 vec3_lerp(Vec3 a, Vec3 b, float t); + * + * Mat4 + * Mat4 mat4_identity(void); + * Mat4 mat4_mul(Mat4 a, Mat4 b); result = a * b (b is applied first) + * Mat4 mat4_translate(Vec3 t); + * Mat4 mat4_scale(Vec3 s); + * Mat4 mat4_rotate_y(float angle); rotates +Z toward +X, i.e. + * (0,0,1) -> (sin a, 0, cos a) + * Mat4 mat4_perspective(float fovy_rad, float aspect, float near, float far); + * standard OpenGL (gluPerspective) form + * Mat4 mat4_look_at(Vec3 eye, Vec3 target, Vec3 up); + * standard OpenGL (gluLookAt) form + * + * CONVENTIONS: Right-handed, Y up. Radians everywhere. Keep each function a + * few lines with a short comment; this is a learning resource. + * Include guard: MATH3D_H. + * + * NOT IN SCOPE: Quaternions, matrix inverse, SIMD, Vec4, generic N-dim math. + * Add a function only when a caller needs it. + * + * DONE WHEN: All functions above compile cleanly under -std=c99 -Wall + * -Wextra, and mat4_perspective * mat4_look_at produces a + * correct view of the ground grid in render.c. + * ============================================================ + */ +#ifndef MATH3D_H +#define MATH3D_H + +#endif /* MATH3D_H */ diff --git a/platformer/src/physics.c b/platformer/src/physics.c new file mode 100644 index 0000000..3608c48 --- /dev/null +++ b/platformer/src/physics.c @@ -0,0 +1,40 @@ +/* + * ============================================================ + * FILE: physics.c + * + * PURPOSE: Moves a Body forward one fixed tick: gravity, integration, + * landing on the ground, and staying inside the world. + * + * FITS IN: Implements physics.h. Called by player.c inside player_update(), + * AFTER the player has chosen its velocity for this tick. Uses + * world_ground_height() and world_clamp_to_bounds() from world.h. + * + * IMPLEMENT physics_step(b, dt), in this order: + * 1. Gravity: if !b->on_ground, vel.y -= GRAVITY * dt, then clamp vel.y to + * no lower than -TERMINAL_VELOCITY. + * (When on the ground, vel.y is left alone. A jump sets it positive + * before this call, and that's what lifts the body off the ground.) + * 2. Integrate (semi-implicit Euler: velocity was updated first, then position): + * pos += vel * dt + * Add a comment explaining why this order is stable enough for a + * fixed timestep. + * 3. Ground: ground = world_ground_height(pos.x, pos.z). + * if pos.y <= ground: pos.y = ground; if vel.y < 0, vel.y = 0; + * on_ground = true + * else: on_ground = false + * Note: on_ground must become false the moment a jump lifts the body, + * and walking off a ledge will also set it false once terrain exists. + * 4. Bounds: pos = world_clamp_to_bounds(pos). If x or z got clamped, + * zero that velocity component so the body doesn't "stick" against + * the edge while pushing into it. + * + * CONVENTIONS: dt is always TICK_DT in practice, but use the parameter rather + * than the constant so the function stays general. + * + * NOT IN SCOPE: Friction/acceleration (that's player movement *intent*, in + * player.c), wall/ceiling collision, slopes, sub-stepping. + * + * DONE WHEN: A body placed at y = 10 falls, speeds up, lands exactly on + * y = 0 with on_ground = true, and stays there. + * ============================================================ + */ diff --git a/platformer/src/physics.h b/platformer/src/physics.h new file mode 100644 index 0000000..dfbfebb --- /dev/null +++ b/platformer/src/physics.h @@ -0,0 +1,36 @@ +/* + * ============================================================ + * FILE: physics.h + * + * PURPOSE: Public interface for generic physical motion: a `Body` that + * falls, moves and lands on the ground. It knows nothing about + * players or controllers, so enemies and objects can reuse it later. + * + * FITS IN: player.c owns a Body, sets its horizontal velocity from input, + * then calls physics_step() once per tick. physics.c asks world.h + * about the ground and the bounds. + * + * INTERFACE: Use these exact names: + * + * typedef struct Body { + * Vec3 pos; position of the body's FEET (bottom center), meters + * Vec3 vel; velocity, meters/second + * bool on_ground; true if the body ended the last step standing on ground + * } Body; + * + * void physics_step(Body *b, float dt); + * + * Include and "math3d.h". + * + * CONVENTIONS: Include guard: PHYSICS_H. + * + * NOT IN SCOPE: Rigid bodies, rotation, mass, forces/impulses API, collision + * between bodies. + * + * DONE WHEN: player.c can move and land using only Body + physics_step. + * ============================================================ + */ +#ifndef PHYSICS_H +#define PHYSICS_H + +#endif /* PHYSICS_H */ diff --git a/platformer/src/player.c b/platformer/src/player.c new file mode 100644 index 0000000..1f1b94c --- /dev/null +++ b/platformer/src/player.c @@ -0,0 +1,73 @@ +/* + * ============================================================ + * FILE: player.c + * + * PURPOSE: The heart of the current milestone: how the character runs, + * turns and jumps. Modeled on SM64's approach: an explicit state + * machine, speed that follows the analog stick, and a facing + * direction that turns toward the stick instead of snapping. + * + * FITS IN: Implements player.h. Reads Input (controls.h). Writes the + * Body's velocity, then calls physics_step() (physics.h) to do the + * actual motion. Tunables all come from config.h. + * + * IMPLEMENT: + * - player_init / player_reset: body.pos = spawn, vel = 0, on_ground = true, + * facing_yaw = 0, forward_speed = 0, state = PLAYER_IDLE. + * + * - player_update(p, in, camera_yaw, dt). Use one static helper per state + * (update_idle / update_run / update_jump / update_fall), dispatched by a + * `switch (p->state)`. Keep each helper short. Shared steps: + * + * A. Stick -> world direction (camera-relative). Using camera.h's convention: + * fwd = (-sin(camera_yaw), 0, -cos(camera_yaw)) + * right = ( cos(camera_yaw), 0, -sin(camera_yaw)) + * wish = fwd * in->move.y + right * in->move.x + * mag = vec2_length(in->move) (0..1, already deadzoned) + * wish_yaw = atan2f(wish.x, wish.z) (only meaningful if mag > 0) + * + * B. Ground movement (IDLE / RUN): + * - If mag > 0: facing_yaw = approach_angle(facing_yaw, wish_yaw, + * PLAYER_TURN_RATE * dt); forward_speed = approachf(forward_speed, + * PLAYER_MAX_SPEED * mag, PLAYER_GROUND_ACCEL * dt) + * - Else: forward_speed = approachf(forward_speed, 0, + * PLAYER_GROUND_FRICTION * dt) + * - State: forward_speed > 0 -> RUN, otherwise IDLE. + * + * C. Jump (from IDLE / RUN): if in->jump_pressed and body.on_ground: + * body.vel.y = PLAYER_JUMP_VELOCITY; on_ground = false; state = JUMP. + * + * D. Air movement (JUMP / FALL): the same as B, but turn rate and accel are + * multiplied by PLAYER_AIR_CONTROL, and there's NO friction when the + * stick is released (you keep your momentum, like SM64). + * - Variable jump height: in JUMP, if !in->jump_held and vel.y > 0, + * multiply vel.y by PLAYER_JUMP_CUT ONCE (don't repeat it every tick; + * either switch to FALL right away or keep a flag). Comment WHY: tapping A + * gives a hop, holding it gives a full jump. + * - JUMP -> FALL when vel.y <= 0. + * - FALL -> IDLE/RUN when body.on_ground (landing). + * - If the player is on the ground state-wise but body.on_ground is false + * (walked off an edge, once edges exist) -> FALL. + * + * E. Apply: body.vel.x = sin(facing_yaw) * forward_speed + * body.vel.z = cos(facing_yaw) * forward_speed + * then physics_step(&p->body, dt). + * + * - player_state_name: a switch that returns string literals. + * + * CONVENTIONS: Facing vector = (sin(yaw), 0, cos(yaw)). Speeds are in m/s, + * accelerations in m/s^2, and every one of them multiplies by dt. + * No magic numbers; everything comes from config.h. + * + * NOT IN SCOPE: Double/triple jump, long jump, wall kick, ground pound, + * skidding/turnaround, slopes, coyote time, jump buffering. + * Leave a short comment at the state enum pointing to the + * README roadmap as the place to grow. + * + * DONE WHEN: Small stick tilts walk slowly and full tilt runs at + * PLAYER_MAX_SPEED. Turning is quick but not instant, and letting go + * of the stick brings the player to a short, smooth stop. A tap of A + * gives a short hop and holding A gives a full ~2.4 m jump. The + * player lands cleanly back in IDLE/RUN. + * ============================================================ + */ diff --git a/platformer/src/player.h b/platformer/src/player.h new file mode 100644 index 0000000..bedfaf4 --- /dev/null +++ b/platformer/src/player.h @@ -0,0 +1,48 @@ +/* + * ============================================================ + * FILE: player.h + * + * PURPOSE: Public interface for the player character: its state and the + * one function that advances it each tick. + * + * FITS IN: main.c owns one Player, calls player_update() each tick, and + * calls player_reset() on Input.reset_pressed. render.c reads it + * to draw it. + * + * INTERFACE: Use these exact names: + * + * typedef enum PlayerState { + * PLAYER_IDLE, on ground, not moving + * PLAYER_RUN, on ground, moving (walk vs run is just speed) + * PLAYER_JUMP, in air, going up after a jump + * PLAYER_FALL in air, going down (or walked off something) + * } PlayerState; + * + * typedef struct Player { + * Body body; position / velocity / on_ground (physics.h) + * float facing_yaw; direction the player faces, radians. + * Facing vector = (sin(yaw), 0, cos(yaw)), + * which matches mat4_rotate_y in math3d.h. + * float forward_speed; ground speed along facing_yaw, m/s (>= 0) + * PlayerState state; + * } Player; + * + * void player_init(Player *p, Vec3 spawn); + * void player_reset(Player *p, Vec3 spawn); + * void player_update(Player *p, const Input *in, float camera_yaw, float dt); + * camera_yaw is a plain float so player.c doesn't depend on camera.h. + * const char *player_state_name(PlayerState s); "IDLE", "RUN", ... for debug + * + * Include "math3d.h", "physics.h", "controls.h". + * + * CONVENTIONS: Include guard: PLAYER_H. + * + * NOT IN SCOPE: Health, animation, extra moves (see README roadmap). + * + * DONE WHEN: main.c and render.c compile against this header alone. + * ============================================================ + */ +#ifndef PLAYER_H +#define PLAYER_H + +#endif /* PLAYER_H */ diff --git a/platformer/src/render.c b/platformer/src/render.c new file mode 100644 index 0000000..a326b15 --- /dev/null +++ b/platformer/src/render.c @@ -0,0 +1,65 @@ +/* + * ============================================================ + * FILE: render.c + * + * PURPOSE: Draws the whole scene with modern OpenGL 3.3 core and as little + * code as possible: a ground grid, the player as a box, and the + * player's drop shadow. + * + * FITS IN: Implements render.h. Reads Camera (camera.h), Player (player.h) + * and world_half_extent()/world_ground_height() (world.h). Uses the + * GL functions that window.c loaded through GLEW. + * + * IMPLEMENT: + * - ONE shader program, source written as string literals in this file + * (no shader files to load): + * vertex: in vec3 a_pos; uniform mat4 u_mvp; gl_Position = u_mvp * vec4(a_pos,1) + * fragment: uniform vec4 u_color; out vec4 frag; frag = u_color + * Add a static helper that compiles a shader and prints the info log + * on failure. Look up the uniform locations once in render_init. + * + * - Three meshes, each a VAO + VBO built once in render_init: + * 1. Ground grid: GL_LINES in the XZ plane at y = 0, one line every + * GRID_SPACING from -world_half_extent() to +world_half_extent(), in + * both directions. Put "major" lines (every GRID_MAJOR_EVERY-th) in a + * SEPARATE draw range so they can get a brighter color. The grid is + * what makes motion readable in a blank world, so explain that in a comment. + * 2. Unit cube: 36 vertices (GL_TRIANGLES), spanning x,z in [-0.5, 0.5] + * and y in [0, 1] so its origin is at the BOTTOM center, matching + * Body.pos being the feet. + * 3. Shadow disc: a GL_TRIANGLE_FAN circle of radius 1 in the XZ plane + * (~24 segments). + * + * - render_frame(cam, player, aspect): + * 1. glClearColor(SKY_COLOR_R/G/B), clear color + depth. + * 2. vp = camera_projection(cam, aspect) * camera_view(cam). + * 3. Grid: u_mvp = vp. Draw minor lines in a dim color, major lines brighter. + * 4. Shadow (drawn BEFORE the player): + * model = translate(player x, ground_y + 0.01, player z) * scale(r, 1, r) + * with r around PLAYER_HALF_WIDTH * 1.2. Dark color. The +0.01 lift + * stops z-fighting with the ground. Comment WHY the shadow exists: + * in SM64 the blob under Mario is the main cue for where you'll land. + * Without it, jumps in 3D are very hard to judge. + * ground_y = world_ground_height(player x, player z). + * 5. Player box: + * model = translate(body.pos) * rotate_y(facing_yaw) + * * scale(2*PLAYER_HALF_WIDTH, PLAYER_HEIGHT, 2*PLAYER_HALF_WIDTH) + * Bright color (e.g. red). Also draw a small second box as a "nose" on + * the front face (+Z in model space) so the facing direction is visible. + * That makes the turn rate tunable by eye. + * Everything uses the one shader, changing only u_mvp and u_color. + * + * - render_shutdown: delete the VAOs, VBOs and the program. + * + * CONVENTIONS: `s_` statics for GL handles. Model matrices built from + * math3d.h helpers. There's no lighting, so flat colors are fine. + * + * NOT IN SCOPE: Lighting, textures, models, text/HUD, anti-aliasing, + * interpolating between ticks (a README roadmap item). + * + * DONE WHEN: The scene shows a sky-colored background, a grid ground plane + * stretching to the world edge, a box with a visible nose that faces + * where it runs, and a shadow that stays on the ground under the + * box during a jump. + * ============================================================ + */ diff --git a/platformer/src/render.h b/platformer/src/render.h new file mode 100644 index 0000000..33e518d --- /dev/null +++ b/platformer/src/render.h @@ -0,0 +1,31 @@ +/* + * ============================================================ + * FILE: render.h + * + * PURPOSE: Public interface for drawing a frame. Rendering only READS game + * state; it never changes the player, the camera or the world. + * + * FITS IN: main.c calls render_init() after window_init(), render_frame() + * once per display frame, and render_shutdown() before + * window_shutdown(). + * + * INTERFACE: Use these exact signatures: + * + * bool render_init(void); compiles shaders, builds meshes. Returns + * false (after printing why) on failure. + * void render_frame(const Camera *cam, const Player *player, float aspect); + * void render_shutdown(void); frees GL objects + * + * Include , "camera.h", "player.h". + * + * CONVENTIONS: Include guard: RENDER_H. + * + * NOT IN SCOPE: A general renderer / scene graph, materials, textures, text. + * + * DONE WHEN: main.c can draw everything with these three calls. + * ============================================================ + */ +#ifndef RENDER_H +#define RENDER_H + +#endif /* RENDER_H */ diff --git a/platformer/src/window.c b/platformer/src/window.c new file mode 100644 index 0000000..455b249 --- /dev/null +++ b/platformer/src/window.c @@ -0,0 +1,44 @@ +/* + * ============================================================ + * FILE: window.c + * + * PURPOSE: Creates and owns the single game window and its OpenGL context. + * This is the ONLY file that calls GLFW window/context functions + * and glewInit. (controls.c calls GLFW input functions.) + * + * FITS IN: main.c calls window_init() first and window_shutdown() last. + * Every frame main.c calls window_poll_events() and window_swap(). + * Implements the interface in window.h. + * + * IMPLEMENT: + * - Private state: `static GLFWwindow *s_window;` + * - Include order matters: BEFORE . + * - window_init(): + * 1. glfwSetErrorCallback -> print GLFW errors to stderr. + * 2. glfwInit(). Note that this also initializes GLFW's joystick/gamepad + * support, which controls.c depends on. + * 3. Hints: GL 3.3, GLFW_OPENGL_CORE_PROFILE, GLFW_OPENGL_FORWARD_COMPAT. + * 4. Create a WINDOW_WIDTH x WINDOW_HEIGHT window titled WINDOW_TITLE + * (config.h), make its context current. + * 5. glewExperimental = GL_TRUE; glewInit(). With a core profile, glewInit + * can leave a harmless GL_INVALID_ENUM behind, so call glGetError() + * once to clear it and add a comment explaining why. + * 6. glfwSwapInterval(1) for vsync. + * 7. Framebuffer-size callback -> glViewport(0, 0, w, h). + * 8. Enable GL_DEPTH_TEST here (it's global GL state set once). + * On any failure: print a clear message, clean up, return false. + * - window_framebuffer_size / window_aspect: use glfwGetFramebufferSize + * (NOT the window size, because they differ on HiDPI displays). Guard against + * height == 0 (minimized window) so the aspect never divides by zero. + * - Everything else is a thin wrapper over the matching glfw* call. + * + * CONVENTIONS: `s_` prefix for file-private statics. Messages go to stderr. + * + * NOT IN SCOPE: Input handling (that's controls.c), drawing (render.c), + * fullscreen, window icons, resizable-minimum-size logic. + * + * DONE WHEN: A window opens at the configured size and title with a + * 3.3 core context, closes cleanly, and resizing it keeps the + * viewport correct. + * ============================================================ + */ diff --git a/platformer/src/window.h b/platformer/src/window.h new file mode 100644 index 0000000..c40dc9e --- /dev/null +++ b/platformer/src/window.h @@ -0,0 +1,43 @@ +/* + * ============================================================ + * FILE: window.h + * + * PURPOSE: Public interface for the OS window, the OpenGL context and the + * clock. Hides GLFW/GLEW setup from the rest of the game. + * + * FITS IN: Called by main.c (lifecycle, loop), render.c (aspect ratio / + * framebuffer size), and controls.c (window handle, only for + * the keyboard fallback). + * + * INTERFACE: Use these exact signatures: + * + * bool window_init(void); + * Creates the window + GL 3.3 core context, loads GL via GLEW. + * Returns false (after printing why to stderr) on failure. + * void window_shutdown(void); + * bool window_should_close(void); + * void window_request_close(void); e.g. when Start/Esc is pressed + * void window_poll_events(void); once per display frame + * void window_swap(void); present the finished frame + * double window_time(void); seconds since start (double for + * precision over long sessions) + * void window_framebuffer_size(int *w, int *h); in PIXELS (for glViewport) + * float window_aspect(void); framebuffer width / height + * void window_set_title(const char *title); used for a debug readout + * struct GLFWwindow *window_handle(void); ONLY controls.c may use this + * + * Include . Forward-declare `struct GLFWwindow;` rather than + * including GLFW here, so files that include window.h don't pull in GLFW. + * + * CONVENTIONS: Include guard: WINDOW_H. + * + * NOT IN SCOPE: Fullscreen toggle, multiple windows, mouse capture. + * + * DONE WHEN: The header compiles on its own and main.c can drive the whole + * window lifecycle through it. + * ============================================================ + */ +#ifndef WINDOW_H +#define WINDOW_H + +#endif /* WINDOW_H */ diff --git a/platformer/src/world.c b/platformer/src/world.c new file mode 100644 index 0000000..2dffb72 --- /dev/null +++ b/platformer/src/world.c @@ -0,0 +1,29 @@ +/* + * ============================================================ + * FILE: world.c + * + * PURPOSE: The blank test world: an empty, flat square of ground where we + * tune movement. It stays empty on purpose, like the test space + * SM64's team used before building real levels. + * + * FITS IN: Implements world.h. Has no dependencies besides config.h and + * math3d.h. physics.c is its main caller. + * + * IMPLEMENT: + * - world_init(): nothing to do yet. Leave a comment saying this is where + * level data would be loaded. + * - world_ground_height(x, z): return 0.0f. Mark the unused parameters with + * (void)x; (void)z; so -Wextra stays quiet, and add a comment saying this + * is where a heightmap/platform lookup will go. + * - world_clamp_to_bounds(p): clamp p.x and p.z with clampf from math3d.h. + * - world_spawn_point(): return vec3_make(0, 0, 0). + * - world_half_extent(): return WORLD_HALF_EXTENT. + * + * CONVENTIONS: Y up. The ground surface is the plane y = world_ground_height. + * + * NOT IN SCOPE: Anything that isn't flat ground. Don't build a collision + * system "for later"; add it when the first platform shows up. + * + * DONE WHEN: It compiles warning-free, and the player can't leave the square. + * ============================================================ + */ diff --git a/platformer/src/world.h b/platformer/src/world.h new file mode 100644 index 0000000..9553938 --- /dev/null +++ b/platformer/src/world.h @@ -0,0 +1,40 @@ +/* + * ============================================================ + * FILE: world.h + * + * PURPOSE: Public interface for "the level". Today the level is a blank, + * flat square of ground, and this API is how other modules ask + * questions about it. + * + * FITS IN: physics.c asks for the ground height and bounds. main.c asks + * for the spawn point. render.c asks for the extent so it knows + * how big a grid to draw. + * + * INTERFACE: Use these exact signatures: + * + * void world_init(void); + * float world_ground_height(float x, float z); + * Height of the ground at (x, z). Returns 0.0f for now. This is + * the one hook where terrain/platforms will plug in later. + * Vec3 world_clamp_to_bounds(Vec3 p); + * Returns p with x and z clamped to [-WORLD_HALF_EXTENT, + * +WORLD_HALF_EXTENT]. y is untouched. + * Vec3 world_spawn_point(void); + * Where the player starts / resets to: (0, 0, 0) for now. + * float world_half_extent(void); + * Returns WORLD_HALF_EXTENT (so render.c doesn't need config + * knowledge of the world's shape). + * + * Include "math3d.h". + * + * CONVENTIONS: Include guard: WORLD_H. + * + * NOT IN SCOPE: Level files, platforms, walls, slopes, objects. + * + * DONE WHEN: physics.c and render.c can be written using only this header. + * ============================================================ + */ +#ifndef WORLD_H +#define WORLD_H + +#endif /* WORLD_H */ -- cgit v1.2.3-18-g5258