dev-physics-lesson

name	dev-physics-lesson
description	Add a physics lesson — particle dynamics, rigid bodies, collisions, constraints, rendered with SDL GPU
argument-hint	[number] [topic-name] [description]

Every physics lesson produces two things: library code and a demo program. The library — common/physics/forge_physics.h — is the crown jewel. The lessons teach concepts; the library is what remains when the learning is done. It must be thorough, correct, performant, tested, safe, and valid. The demo program visualizes the library in action, rendered in real time with SDL GPU.

When to use this skill:

• You need to teach particle dynamics, rigid body physics, or collision detection
• A learner wants to understand integration, forces, impulses, or constraints
• The concept benefits from a live 3D visualization showing behavior over time
• New functionality needs to be added to common/physics/forge_physics.h

Smart behavior:

• Before creating a lesson, check if an existing physics lesson already covers it
• Library first, demo second. Design, implement, document, and test the library code before writing a single line of the demo program. The demo exercises the library — it does not replace it.
• Physics lessons are visual — every concept must be observable in the running program
• Focus on why the math works, not just the code — connect equations to behavior
• Use simple geometric shapes (cubes, spheres, capsules) — the physics is the star
• All scene geometry comes from common/shapes/forge_shapes.h — never write inline geometry generation functions
• Cross-reference math lessons (vectors, matrices, quaternions) and GPU lessons where relevant

Arguments

The user (or you) can provide:

• Number: two-digit lesson number (e.g. 01, 02)
• Topic name: kebab-case (e.g. point-particles, springs-and-constraints)
• Description: what this teaches (e.g. "Symplectic Euler integration, gravity, drag")

If any are missing, infer from context or ask.

Steps

1. Analyze what's needed

• Check existing physics lessons: Is there already a lesson for this topic?
• Check common/physics/: Does relevant library code already exist?
• Check common/shapes/forge_shapes.h: Does the shapes library already provide every shape the lesson needs? If a required shape is missing, plan to add it to forge_shapes.h (not inline in the lesson).
• Identify the scope: What specific physics concepts does this lesson cover?
• Find cross-references: Which math/GPU lessons relate?
• Check PLAN.md: Where does this lesson fit in the physics track?

2. Create the lesson directory

lessons/physics/NN-topic-name/

With subdirectories:

lessons/physics/NN-topic-name/
  main.c
  CMakeLists.txt
  README.md
  assets/

Baseline rendering shaders (shadow, scene, grid, sky, UI) are provided by forge_scene.h — no per-lesson copies needed. If the lesson introduces a topic-specific shader (e.g. a debug visualization pass), add a shaders/ subdirectory for those files only.

3. Design and implement the physics library code

Every physics lesson adds to common/physics/forge_physics.h. This is not optional — it is the primary deliverable. The demo program exists to exercise and visualize the library; the library is what ships.

For the first physics lesson, create the file. For subsequent lessons, extend it. Design the API before writing the demo. The demo calls the library — never the reverse.

Library standards

These standards are non-negotiable. The physics library is safety-critical code — incorrect integration, missed edge cases, or division by zero produce simulations that explode, tunnel through geometry, or silently drift. Every function must be defensible.

Correctness:

• Every function must implement a named, well-understood algorithm (symplectic Euler, Verlet, GJK, sequential impulse). Cite the source in the doc comment — a textbook, paper, or established reference.
• Equations in the README must correspond exactly to the code. If the README shows $v(t + \Delta t) = v(t) + a \cdot \Delta t$, the code must compute that expression in that order. No silent rearrangements.
• Collision detection must handle degenerate cases: zero-length normals, coincident positions, zero-radius shapes, zero-mass bodies. Document what each function does when given degenerate input.
• Integration must preserve physical invariants where the algorithm guarantees it. Symplectic Euler preserves phase-space volume — verify this in tests by checking energy over long runs.

Numerical safety:

• Never divide without checking the denominator. Guard 1.0f / mass with an inv_mass field precomputed at construction, where mass == 0 means infinite mass (static object) and inv_mass == 0.
• Normalize vectors only after checking length > epsilon. Use vec3_length() and compare against 1e-6f before calling vec3_normalize().
• Clamp values that have physical bounds: restitution to [0, 1], damping to [0, 1], penetration depth to >= 0. Document the valid range in the parameter comment.
• Use SDL_fabsf() for float comparisons, not ==. Two floats are "equal" if SDL_fabsf(a - b) < epsilon.

Performance:

• Precompute values that do not change per-frame: inverse mass, inverse inertia tensor, bounding radii.
• Avoid SDL_sqrtf() when the squared value suffices — distance comparisons, broadphase overlap tests, and radius checks should use squared distances.
• Broadphase before narrowphase: never run O(n) narrowphase tests when a spatial partition or sort-and-sweep can reject pairs early.
• Profile-guided decisions only. Do not optimise speculatively — measure first. But do not pessimise either: an O(n^2) all-pairs check is unacceptable when n > 64.

Safety and validation:

• Every public function documents its preconditions. If dt must be positive, say so. If a pointer must be non-NULL, say so.
• Init functions (forge_physics_particle_create, etc.) must produce a valid object with all fields initialised — no partially constructed state.
• Functions that mutate state (integration, impulse application) must leave the object in a valid state even if called with extreme inputs (very large dt, very large forces). Clamp or early-return rather than producing NaN or infinity.
• Never read uninitialised memory. Every struct field must have an explicit initial value in the init function.

Header-only implementation:

• static inline for all functions — no separate .c compilation unit
• Guard with #ifndef FORGE_PHYSICS_H / #define / #endif
• Include "math/forge_math.h", "containers/forge_containers.h", and <SDL3/SDL.h> — never include <math.h>, <string.h>, or <stdlib.h> directly
• Use dynamic arrays (forge_containers.h) for variable-size outputs (contacts, SAP pairs)
• Deterministic: identical inputs and fixed timestep produce identical outputs

Documentation (every function, no exceptions):

/* Apply gravitational acceleration to a particle.
 *
 * Adds gravity * mass to the particle's force accumulator. Static
 * particles (inv_mass == 0) are unaffected.
 *
 * This uses Newton's second law: F = m * g. The force accumulator
 * stores the total force; integration divides by mass to get
 * acceleration.
 *
 * Parameters:
 *   p       — particle to apply gravity to (must not be NULL)
 *   gravity — gravitational acceleration, typically (0, -9.81, 0)
 *
 * Usage:
 *   forge_physics_apply_gravity(&particle, (vec3){0, -9.81f, 0});
 *
 * See: Physics Lesson 01 — Point Particles
 * Ref: Millington, "Game Physics Engine Development", Ch. 3
 */
static inline void forge_physics_apply_gravity(ForgePhysicsParticle *p,
                                               vec3 gravity)
{
    if (p->inv_mass == 0.0f) return;  /* static — no forces apply */
    /* F = m * g, but we accumulate force and divide by mass later */
    p->force_accum = vec3_add(p->force_accum,
                              vec3_scale(gravity, p->mass));
}

Every doc comment must include:

• Summary (one sentence — what it does)
• Algorithm or physical law being implemented
• Parameters with types, valid ranges, and nullability
• Return value (if any) with units
• Usage example
• Cross-reference to the lesson that introduces it
• Reference to the source material (textbook, paper)

Naming:

• Functions: forge_physics_verb_noun() — e.g. forge_physics_integrate(), forge_physics_apply_gravity(), forge_physics_collide_sphere_plane()
• Types: ForgePhysicsNoun — e.g. ForgePhysicsParticle, ForgePhysicsContact, ForgePhysicsRigidBody
• Constants: FORGE_PHYSICS_UPPER — e.g. FORGE_PHYSICS_MAX_VELOCITY

Core types to establish in Lesson 01:

#ifndef FORGE_PHYSICS_H
#define FORGE_PHYSICS_H

#include <SDL3/SDL.h>
#include "math/forge_math.h"
#include "containers/forge_containers.h"
#include "arena/forge_arena.h"

/* --- Particle ----------------------------------------------------------- */

typedef struct ForgePhysicsParticle {
    vec3  position;
    vec3  velocity;
    vec3  acceleration;    /* accumulated forces / mass this frame         */
    vec3  force_accum;     /* forces accumulated before integration        */
    float mass;            /* kg — zero means infinite mass (immovable)    */
    float inv_mass;        /* 1/mass — precomputed, 0 for static objects   */
    float damping;         /* velocity damping per frame [0..1]            */
    float restitution;     /* coefficient of restitution [0..1]            */
} ForgePhysicsParticle;

/* ... functions grow lesson by lesson ... */

#endif /* FORGE_PHYSICS_H */

Testing the library (MANDATORY)

The physics library is tested independently of the demo program. Tests validate correctness, edge cases, numerical stability, and determinism. Every function added to forge_physics.h must have corresponding tests in tests/physics/test_physics.c.

Test categories (every function must have all applicable categories):

1. Basic correctness — Known inputs produce expected outputs within tolerance. Use hand-computed reference values, not "whatever the code outputs."

   /* Gravity on a 2 kg particle for 1 second should produce v = -9.81 m/s */
   ForgePhysicsParticle p = forge_physics_particle_create(
       (vec3){0, 10, 0},  /* position */
       2.0f,              /* mass */
       0.0f,              /* damping */
       1.0f);             /* restitution */
   forge_physics_apply_gravity(&p, (vec3){0, -9.81f, 0});
   forge_physics_integrate(&p, 1.0f);
   ASSERT_NEAR(p.velocity.y, -9.81f, 1e-4f);
   

2. Edge cases — Zero mass (static), zero dt, zero-length vectors, coincident positions, maximum velocity, very large forces.

   /* Static particle (inv_mass == 0) must not move under any force */
   ForgePhysicsParticle p = forge_physics_particle_create(
       (vec3){5, 0, 0},   /* position */
       0.0f,              /* mass (0 → static) */
       0.0f,              /* damping */
       1.0f);             /* restitution */
   forge_physics_apply_gravity(&p, (vec3){0, -9.81f, 0});
   forge_physics_integrate(&p, 1.0f);
   ASSERT_NEAR(p.position.x, 5.0f, 1e-6f);
   ASSERT_NEAR(p.velocity.y, 0.0f, 1e-6f);
   

3. Conservation and stability — Run a closed system for thousands of steps. Total energy (kinetic + potential) should remain bounded for symplectic integrators. Explicit check: no NaN, no infinity, no position > 1e6.

   /* 10000 steps of a bouncing ball — energy must not grow unboundedly */
   for (int i = 0; i < 10000; i++) {
       forge_physics_apply_gravity(&p, gravity);
       forge_physics_integrate(&p, PHYSICS_DT);
       /* ... collision with ground ... */
   }
   float energy = kinetic_energy(&p) + potential_energy(&p, gravity);
   ASSERT(energy < initial_energy * 1.1f); /* bounded growth */
   ASSERT(!isnan(p.position.x) && !isinf(p.position.x));
   

4. Determinism — Two runs with identical inputs must produce identical outputs, bit-for-bit. This is a requirement for replay systems and debugging.

   /* Two particles with identical setup must produce identical state */
   ForgePhysicsParticle a = make_test_particle();
   ForgePhysicsParticle b = make_test_particle();
   for (int i = 0; i < 1000; i++) {
       step(&a, PHYSICS_DT);
       step(&b, PHYSICS_DT);
   }
   ASSERT(vec3_equal(a.position, b.position));
   ASSERT(vec3_equal(a.velocity, b.velocity));
   ASSERT(a.inv_mass == b.inv_mass);
   

5. Collision-specific — Normals point from B to A. Penetration depth is non-negative. Post-resolution velocity respects restitution. Tangential velocity is preserved (or reduced by friction, not reversed).

Test infrastructure:

• Test file: tests/physics/test_physics.c
• Register in root CMakeLists.txt as test_physics
• Use the same ASSERT_NEAR / test macros as tests/math/test_math.c
• Run: cmake --build build --target test_physics && ctest --test-dir build -R physics
• Tests must pass before the demo program is written

For the first physics lesson, also create common/physics/README.md with the full API reference, following the format of common/math/README.md.

4. Create the demo program (main.c)

A focused C program that simulates a physics scenario and renders it in real time using SDL GPU. Physics lessons are interactive 3D applications with full rendering — not console programs.

MANDATORY: Use forge_scene.h for the rendering baseline. The scene library provides Blinn-Phong lighting, shadow mapping, grid floor, sky gradient, FPS camera, and UI in a single forge_scene_init() call. This eliminates hundreds of lines of rendering boilerplate and lets the lesson focus on physics. See the forge-scene-renderer skill for the full API.

The rendering baseline (provided by forge_scene.h):

1. Blinn-Phong lighting — Per-material ambient + diffuse + specular
2. Procedural grid floor — Anti-aliased shader grid on XZ plane
3. Directional shadow map — Single shadow map with PCF
4. Sky gradient — Procedural sky background
5. First-person camera — WASD + mouse look with delta time
6. UI system — Immediate-mode forge UI for controls
7. Capture support — forge_capture.h integration (when FORGE_CAPTURE defined)

Physics simulation requirements:

• Fixed timestep — Physics runs at a fixed rate (e.g. 60 Hz) with accumulator-based stepping. Rendering interpolates between physics states for smooth visuals at any frame rate:

  #define PHYSICS_DT (1.0f / 60.0f)
  
  /* In SDL_AppIterate: */
  state->accumulator += dt;
  while (state->accumulator >= PHYSICS_DT) {
      physics_step(state, PHYSICS_DT);
      state->accumulator -= PHYSICS_DT;
  }
  float alpha = state->accumulator / PHYSICS_DT;
  /* Interpolate positions for rendering: lerp(prev, curr, alpha) */
  

• Force accumulator pattern — Forces are accumulated each step, then cleared after integration:

  /* Apply forces */
  forge_physics_apply_gravity(&particle, (vec3){0, -9.81f, 0});
  forge_physics_apply_drag(&particle, drag_coeff);
  
  /* Integrate (symplectic Euler) */
  forge_physics_integrate(&particle, dt);
  
  /* Clear forces for next step */
  particle.force_accum = vec3_zero();
  

• Reset key — Press R to reset the simulation to its initial state. This is essential for physics demos where objects settle or leave the scene.

• Pause key — Press P to pause/resume the simulation. Rendering and camera controls continue while paused.

• Slow motion — Press T to toggle half-speed simulation for observing fast phenomena.

Scene geometry via forge_shapes.h (MANDATORY):

All scene geometry must come from common/shapes/forge_shapes.h. Never write inline geometry generation functions — use the shared library so every lesson benefits from the same tested, documented shapes.

• Sphere: forge_shapes_sphere(32, 16) or forge_shapes_icosphere(1)
• Box/Cube: forge_shapes_cube(1, 1) — use forge_shapes_compute_flat_normals() for face normals
• Capsule: forge_shapes_capsule(32, 8, 8, 1.0f)
• Cylinder: forge_shapes_cylinder(32, 1)
• Torus: forge_shapes_torus(32, 16, major, tube)
• Ground plane: Handled by the shader grid (no geometry needed)

If the lesson requires a shape that forge_shapes.h does not yet provide, add it to the library first — following the existing API conventions (unit-scale, centred at origin, CCW winding, struct-of-arrays layout). Update common/shapes/README.md and add tests under tests/shapes/.

#include "shapes/forge_shapes.h"

/* Generate shapes at init time, upload to GPU, then free CPU copies.
 * Always check vertex_count — generators return an empty shape
 * (all pointers NULL, counts 0) if allocation fails.
 *
 * CRITICAL: ForgeShape uses struct-of-arrays (separate positions[] and
 * normals[]), but forge_scene.h shaders expect interleaved ForgeSceneVertex.
 * You MUST convert via upload_shape_vb() — never upload raw SoA data. */

/* Helper: convert ForgeShape SoA to ForgeSceneVertex AoS and upload */
static SDL_GPUBuffer *upload_shape_vb(ForgeScene *scene,
    const ForgeShape *shape)
{
    if (!shape || !shape->positions || shape->vertex_count == 0) return NULL;
    ForgeSceneVertex *verts = SDL_calloc(
        (size_t)shape->vertex_count, sizeof(ForgeSceneVertex));
    if (!verts) return NULL;
    for (int i = 0; i < shape->vertex_count; i++) {
        verts[i].position = shape->positions[i];
        verts[i].normal   = shape->normals
            ? shape->normals[i]
            : (vec3){ 0.0f, 0.0f, 0.0f };
    }
    SDL_GPUBuffer *buf = forge_scene_upload_buffer(scene,
        SDL_GPU_BUFFERUSAGE_VERTEX, verts,
        (Uint32)shape->vertex_count * (Uint32)sizeof(ForgeSceneVertex));
    SDL_free(verts);
    return buf;
}

/* In SDL_AppInit: */
ForgeShape sphere = forge_shapes_sphere(32, 16);
if (sphere.vertex_count == 0) {
    SDL_Log("Failed to generate sphere");
    return SDL_APP_FAILURE;
}
state->sphere_vb = upload_shape_vb(&state->scene, &sphere);
state->sphere_ib = forge_scene_upload_buffer(&state->scene,
    SDL_GPU_BUFFERUSAGE_INDEX, sphere.indices,
    (Uint32)sphere.index_count * (Uint32)sizeof(uint32_t));
state->sphere_idx_count = (int)sphere.index_count;
forge_shapes_free(&sphere);
if (!state->sphere_vb || !state->sphere_ib) {
    SDL_Log("Failed to upload sphere mesh");
    return SDL_APP_FAILURE;
}

ForgeShape box = forge_shapes_cube(1, 1);
if (box.vertex_count == 0) {
    SDL_Log("Failed to generate box");
    return SDL_APP_FAILURE;
}
forge_shapes_compute_flat_normals(&box);  /* face normals for rigid bodies */
state->box_vb = upload_shape_vb(&state->scene, &box);
state->box_ib = forge_scene_upload_buffer(&state->scene,
    SDL_GPU_BUFFERUSAGE_INDEX, box.indices,
    (Uint32)box.index_count * (Uint32)sizeof(uint32_t));
state->box_idx_count = (int)box.index_count;
forge_shapes_free(&box);
if (!state->box_vb || !state->box_ib) {
    SDL_Log("Failed to upload box mesh");
    return SDL_APP_FAILURE;
}

Template structure:

/*
 * Physics Lesson NN — Topic Name
 *
 * Demonstrates: [what this shows]
 *
 * Controls:
 *   WASD / Arrow keys — move camera
 *   Mouse             — look around
 *   R                 — reset simulation
 *   P                 — pause / resume
 *   T                 — toggle slow motion
 *   Escape            — release mouse / quit
 *
 * SPDX-License-Identifier: Zlib
 */

#define SDL_MAIN_USE_CALLBACKS 1
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>
#include <stddef.h>

#include "math/forge_math.h"
#include "physics/forge_physics.h"
#include "shapes/forge_shapes.h"

#define FORGE_SCENE_IMPLEMENTATION
#include "scene/forge_scene.h"

/* ── Constants ────────────────────────────────────────────────────── */

#define PHYSICS_DT     (1.0f / 60.0f)

/* UI panel position and size — adjust to fit your lesson's controls */
#define PANEL_X  20.0f
#define PANEL_Y  60.0f
#define PANEL_W  280.0f
#define PANEL_H  200.0f

/* ── Types ────────────────────────────────────────────────────────── */

typedef struct app_state {
    ForgeScene scene;  /* rendering, camera, shadow map, grid, sky, UI */

    /* GPU resources — app-owned geometry */
    SDL_GPUBuffer *sphere_vb, *sphere_ib;
    SDL_GPUBuffer *box_vb, *box_ib;
    int sphere_idx_count, box_idx_count;

    /* Timing / simulation control */
    float accumulator;   /* fixed-timestep accumulator (seconds)       */
    float sim_time;      /* total simulated time (seconds)             */
    bool  paused;        /* true = physics frozen, camera still works  */
    bool  slow_motion;   /* true = half-speed simulation               */

    /* Physics state — lesson-specific */
    /* ForgePhysicsParticle particles[N]; */
    /* ... */

    /* UI */
    ForgeUiWindowState ui_window;  /* draggable info panel state */
} app_state;

Init pattern:

SDL_AppResult SDL_AppInit(void **appstate, int argc, char **argv)
{
    app_state *state = SDL_calloc(1, sizeof(*state));
    if (!state) return SDL_APP_FAILURE;
    *appstate = state;

    ForgeSceneConfig cfg = forge_scene_default_config("Physics NN — Topic");
    cfg.cam_start_pos = vec3_create(0.0f, 4.0f, 12.0f);
    cfg.font_path = "assets/fonts/liberation_mono/LiberationMono-Regular.ttf";

    if (!forge_scene_init(&state->scene, &cfg, argc, argv))
        return SDL_APP_FAILURE;

    /* Initialize UI window (MANDATORY — zero-size window won't render) */
    state->ui_window = forge_ui_window_state_default(
        PANEL_X, PANEL_Y, PANEL_W, PANEL_H);

    /* Generate and upload shapes (see upload_shape_vb pattern above) ... */
    return SDL_APP_CONTINUE;
}

Iterate pattern:

SDL_AppResult SDL_AppIterate(void *appstate)
{
    app_state *state = appstate;
    ForgeScene *s = &state->scene;

    if (!forge_scene_begin_frame(s)) return SDL_APP_CONTINUE;
    float dt = forge_scene_dt(s);

    /* Fixed-timestep physics */
    if (!state->paused) {
        float step_dt = state->slow_motion ? dt * 0.5f : dt;
        state->accumulator += step_dt;
        while (state->accumulator >= PHYSICS_DT) {
            physics_step(state, PHYSICS_DT);
            state->accumulator -= PHYSICS_DT;
        }
    }

    /* Shadow pass */
    forge_scene_begin_shadow_pass(s);
    /* forge_scene_draw_shadow_mesh(s, vb, ib, count, model); */
    forge_scene_end_shadow_pass(s);

    /* Main pass */
    forge_scene_begin_main_pass(s);
    /* forge_scene_draw_mesh(s, vb, ib, count, model, color); */
    forge_scene_draw_grid(s);
    forge_scene_end_main_pass(s);

    /* UI pass (optional) */
    float mx, my;
    Uint32 buttons = SDL_GetMouseState(&mx, &my);
    forge_scene_begin_ui(s, mx, my, (buttons & SDL_BUTTON_LMASK) != 0);
    /* forge_ui_* calls ... */
    forge_scene_end_ui(s);

    return forge_scene_end_frame(s);
}

5. Shaders

The baseline shaders (scene, grid, shadow, sky, UI) are compiled into forge_scene.h — no per-lesson copies needed. If the lesson introduces a topic-specific shader (e.g. a debug visualization or force-vector overlay), add those files to shaders/ and compile them:

python scripts/compile_shaders.py physics/NN-topic-name

Most physics lessons need no lesson-specific shaders at all.

6. Create CMakeLists.txt

add_executable(NN-topic-name WIN32 main.c)
target_include_directories(NN-topic-name PRIVATE ${FORGE_COMMON_DIR})
target_link_libraries(NN-topic-name PRIVATE SDL3::SDL3
    $<$<NOT:$<C_COMPILER_ID:MSVC>>:m>)
forge_target_assets(NN-topic-name)

if(FORGE_CAPTURE)
    target_compile_definitions(NN-topic-name PRIVATE FORGE_CAPTURE)
endif()

# Copy SDL3 DLL next to executable
if(TARGET SDL3::SDL3-shared)
    add_custom_command(TARGET NN-topic-name POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
            $<TARGET_FILE:SDL3::SDL3-shared>
            $<TARGET_FILE_DIR:NN-topic-name>
        VERBATIM
    )
endif()

Create forge-assets.toml next to CMakeLists.txt:

[assets]
dirs = [
    "fonts/liberation_mono",
]

All assets — fonts, textures, models — come from the pipeline's processed output via the manifest. NEVER write bespoke CMake copy commands for fonts or other assets. See pipeline/README.md for the full manifest reference.

7. Create README.md

Structure:

# Physics Lesson NN — Topic Name

[Brief subtitle explaining the physics concept]

## What you'll learn

[Bullet list of physics and rendering concepts covered]

## Result

<!-- TODO: screenshot -->

[Brief description of what the demo shows. For dynamic simulations, include
both a screenshot AND an animated GIF showing the behavior over time.]

| Screenshot | Animation |
|---|---|
| ![Static view](assets/screenshot.png) | ![Animation](assets/animation.gif) |

**Controls:**

| Key | Action |
|---|---|
| WASD / Arrows | Move camera |
| Mouse | Look around |
| R | Reset simulation |
| P | Pause / resume |
| T | Toggle slow motion |
| Escape | Release mouse / quit |

## The physics

[Main explanation of the physics concepts, with equations and diagrams.
Use KaTeX for formulas and /dev-create-diagram for visualizations.]

### [Core concept 1]

[Explanation with equations. For example:]

Symplectic Euler integration updates velocity before position, which
preserves energy better than explicit Euler:

$$
v(t + \Delta t) = v(t) + a(t) \cdot \Delta t
$$

$$
x(t + \Delta t) = x(t) + v(t + \Delta t) \cdot \Delta t
$$

### [Core concept 2]

[More physics explanation]

## The code

### Fixed timestep

[Explain the accumulator pattern and why fixed timestep matters for physics]

### Simulation step

[Walk through the physics update function with annotated code]

### Rendering

[Explain how physics state maps to rendered objects. This section can be
brief — point readers to the GPU lessons for rendering details.]

## Key concepts

- **Concept 1** — Brief explanation
- **Concept 2** — Brief explanation

## The physics library

This lesson adds the following to `common/physics/forge_physics.h`:

| Function | Purpose |
|---|---|
| `forge_physics_function_name()` | Brief description |

See: [common/physics/README.md](../../../common/physics/README.md)

## Where it's used

- [GPU Lesson NN](../../gpu/NN-name/) uses this for [purpose]
- [Math Lesson NN](../../math/NN-name/) provides the [math concept] used here

## Building

```bash
cmake -B build
cmake --build build --config Debug

# Windows
build\lessons\physics\NN-topic-name\Debug\NN-topic-name.exe

# Linux / macOS
./build/lessons/physics/NN-topic-name/NN-topic-name
```

## Exercises

1. [Exercise extending the physics concept]
2. [Exercise modifying parameters to observe different behavior]
3. [Exercise adding a new force or constraint]

## Further reading

- [Relevant math lesson for the underlying math]
- [External resource — Game Physics Engine Development, Real-Time Collision
  Detection, etc.]

8. Update project files

• CMakeLists.txt (root): Add add_subdirectory(lessons/physics/NN-topic-name) under a "Physics Lessons" section (create the section if it doesn't exist yet, placed after GPU Lessons)
• README.md (root): Add a row to the physics lessons table in a "Physics Lessons (lessons/physics/)" section — follow the same format as the existing track sections. Create the section if this is the first physics lesson.
• lessons/physics/README.md: Create a track README if this is the first lesson, or add a row to the existing lessons table
• PLAN.md: Check off the physics lesson entry

9. Cross-reference other lessons

• Find related math lessons: Vectors, matrices, quaternions, integration
• Find related GPU lessons: Rendering techniques used (lighting, shadows)
• Update those lesson READMEs: Add a note like "See Physics Lesson NN for this concept in action"
• Update physics lesson README: List related lessons in "Where it's used"

10. Build and test

# Compile lesson-specific shaders (skip if lesson has no shaders/ directory)
python scripts/compile_shaders.py physics/NN-topic-name

# Build
cmake -B build
cmake --build build --config Debug

# Run
./build/lessons/physics/NN-topic-name/NN-topic-name

Use a Task agent with model: "haiku" for build commands per project conventions.

Verify:

• The program opens a window with the grid floor visible
• Objects are lit with Blinn-Phong shading and cast shadows
• Camera controls work (WASD + mouse)
• Physics simulation runs (objects move, interact)
• R resets the simulation
• P pauses/resumes
• T toggles slow motion

11. Capture screenshots and GIF

Physics lessons need both a static screenshot and an animated GIF because the physics behavior is inherently dynamic.

# Configure with capture support
cmake -B build -DFORGE_CAPTURE=ON
cmake --build build --config Debug --target NN-topic-name

# Static screenshot
python scripts/capture_lesson.py lessons/physics/NN-topic-name

# Animated GIF (captures multiple frames)
python scripts/capture_lesson.py lessons/physics/NN-topic-name \
    --gif --gif-frames 120 --gif-fps 30

If the GIF capture script does not yet support --gif, capture individual frames and assemble with Pillow:

from PIL import Image
import glob
frames = [Image.open(f) for f in sorted(glob.glob("frame_*.png"))]
frames[0].save("animation.gif", save_all=True, append_images=frames[1:],
               duration=33, loop=0, optimize=True)

Copy output to lessons/physics/NN-topic-name/assets/.

12. Verify key topics are fully explained

Before finalizing, launch a verification agent using the Task tool (subagent_type: "general-purpose"). Give the agent the paths to the lesson's README.md and main.c and ask it to audit every key topic for completeness.

For each key topic / "What you'll learn" bullet, the agent must check:

1. Explained in the README — Is the concept described clearly enough that a reader encountering it for the first time could understand it?
2. Demonstrated in the program — Does main.c actually exercise this concept with visible behavior?
3. All referenced terms are defined — Read the exact wording of each key topic and identify every technical term. For each term, confirm it is explained somewhere in the lesson.
4. Equations match code — Every formula in the README should have a corresponding implementation in the code, and vice versa.

The lesson is incomplete until every key topic passes all four checks.

13. Run markdown linting

Use the /dev-markdown-lint skill to check all markdown files:

npx markdownlint-cli2 "**/*.md"

If errors are found:

1. Try auto-fix: npx markdownlint-cli2 --fix "**/*.md"
2. Manually fix remaining errors (especially MD040 - missing language tags)
3. Verify: npx markdownlint-cli2 "**/*.md"

Physics Lesson Conventions

Scope

Physics lessons cover simulation concepts rendered in real time:

• Particle dynamics — Position, velocity, acceleration, integration, forces (gravity, drag, springs)
• Rigid body physics — Mass, inertia tensor, angular velocity, torque
• Collision detection — Sphere-sphere, sphere-plane, AABB, OBB, GJK/EPA
• Contact resolution — Impulse-based response, friction, restitution
• Constraints — Distance constraints, joints, solver iteration
• Simulation architecture — Fixed timestep, interpolation, sleeping, broadphase/narrowphase

Physics lessons do not cover:

• Advanced rendering techniques in depth (point to GPU lessons instead)
• Mathematical derivations from scratch (point to math lessons instead)
• Game-specific systems (AI, networking, UI)

Rendering baseline

Every physics lesson includes the same rendering foundation so the focus stays on the physics. This baseline is not optional — it ensures consistent visual quality across the track.

Use forge_scene.h — one forge_scene_init() call provides all of the following. See the forge-scene-renderer skill for the full API.

Feature	Provided by forge_scene.h	Original skill reference
Blinn-Phong lighting	Per-material ambient + diffuse + specular	forge-blinn-phong-materials
Procedural grid floor	Anti-aliased shader grid on XZ plane	forge-shader-grid
Shadow map	Single directional shadow map with PCF	forge-cascaded-shadow-maps
Sky gradient	Procedural sky background	forge-procedural-sky
Camera controls	WASD + mouse look with delta time	forge-camera-and-input
Depth buffer	Depth testing with appropriate format	forge-depth-and-3d
sRGB swapchain	SDR_LINEAR for correct gamma	forge-sdl-gpu-setup
UI system	Immediate-mode forge UI	forge-ui-rendering
Procedural geometry	All shapes from forge_shapes.h	forge-procedural-geometry
Capture support	Screenshot + GIF via forge_capture.h	dev-add-screenshot

Simulation controls

Every physics lesson must support these controls:

Key	Action	Purpose
R	Reset simulation	Return all objects to initial positions and velocities
P	Pause / resume	Freeze physics while camera still works
T	Toggle slow motion	Run at half speed for observing fast phenomena

Fixed timestep

Physics must run at a fixed rate, decoupled from rendering. The accumulator pattern prevents instability from variable frame rates:

state->accumulator += render_dt;
while (state->accumulator >= PHYSICS_DT) {
    /* Store previous state for interpolation */
    store_previous_state(state);
    /* Step physics */
    physics_step(state, PHYSICS_DT);
    state->accumulator -= PHYSICS_DT;
}
/* Interpolation factor for smooth rendering */
float alpha = state->accumulator / PHYSICS_DT;

Without fixed timestep, physics behaves differently at different frame rates — objects fall faster on slow machines and slower on fast ones.

Simple geometry via forge_shapes.h

Physics lessons use procedural geometry from common/shapes/forge_shapes.h, generated at init time. No model loading (no glTF, no OBJ), and no inline geometry generation functions — all shapes come from the shared library.

If a lesson needs a shape that forge_shapes.h does not provide, add it to the library first (following the existing conventions: unit-scale, origin- centred, CCW winding, struct-of-arrays layout), update common/shapes/README.md, and add tests under tests/shapes/. Then use it from the lesson like any other shape.

Shape	forge_shapes.h call	Use case
Sphere	forge_shapes_sphere(32, 16)	Particles, balls
Icosphere	forge_shapes_icosphere(1)	Low-poly particles
Box/Cube	forge_shapes_cube(1, 1) + forge_shapes_compute_flat_normals()	Rigid bodies, walls
Capsule	forge_shapes_capsule(32, 8, 8, 1.0f)	Collision shapes
Cylinder	forge_shapes_cylinder(32, 1)	Axles, rods
Torus	forge_shapes_torus(32, 16, major, tube)	Ring shapes
Cone	forge_shapes_cone(32, 1)	Force direction indicators

See common/shapes/README.md for the full API and Asset Lesson 04 for a walkthrough.

Visual identity for physics objects

Use the Devernay/OpenGL material tables for consistent object appearance:

• Dynamic objects — Bright, saturated materials (red plastic, gold, jade) so motion is easy to track
• Static objects — Muted, dark materials (gray stone, dark rubber) so they recede visually
• Constraint visualization — Thin lines or wireframe between connected objects (use debug line rendering if available)
• Force vectors — Optional overlay arrows showing forces, velocities, or contact normals for educational value

Tone

Physics lessons should be rigorous but accessible. Simulation programming has deep mathematical roots — treat every concept with respect while making it approachable.

• Name the methods — "Symplectic Euler", "Verlet integration", "GJK algorithm" — named techniques carry weight and help readers find resources
• Show the math, then the code — Present the equation first, then show the C implementation line by line
• Explain stability — Why some integrators blow up, why fixed timestep matters, why damping is needed
• Encourage experimentation — Physics is best learned by changing parameters and observing results. Exercises should modify gravity, restitution, mass, and other values.

Code style

Follow the same conventions as all forge-gpu code:

• C99, matching SDL's style
• ForgePhysics prefix for public types, forge_physics_ for functions
• PascalCase for typedefs, lowercase_snake_case for locals
• UPPER_SNAKE_CASE for #define constants
• No magic numbers — #define or enum everything
• Extensive comments explaining why and purpose

Asset Pipeline Mandate

• All physics shapes (spheres, cubes, capsules, planes) MUST be created via forge_shapes_*() from common/shapes/forge_shapes.h.
• NEVER define inline vertex arrays for physics bodies.
• If a lesson needs textured objects, load via forge_pipeline_load_texture().
• The procedural grid floor may remain shader-generated.
• All assets must go through the pipeline and be declared via forge-assets.toml manifests. NEVER write bespoke CMake copy commands for fonts, textures, or models. Use forge_target_assets() in CMakeLists.txt and list dependencies in the manifest.
• Lesson-local assets/ directories hold only screenshots and diagrams for the README — never runtime assets.

Diagrams and Formulas

Find opportunities to create compelling diagrams and visualizations via the matplotlib scripts — they increase reader engagement and help learners understand the topics being taught. Use the /dev-create-diagram skill to add diagrams following the project's visual identity and quality standards.

KaTeX math

Physics lessons will use formulas extensively. Use inline $...$ and display $$...$$ math notation:

• Inline: $F = ma$, $v(t + \Delta t) = v(t) + a \cdot \Delta t$
• Display math blocks must be split across three lines (CI enforces this):

$$
F = ma
$$

Matplotlib diagrams

For force diagrams, collision geometry, phase space plots, and integration comparisons, add diagram functions to scripts/forge_diagrams/physics/lesson_NN.py (create the file if it doesn't exist):

1. Write a function following the existing pattern
2. Re-export from scripts/forge_diagrams/physics/__init__.py
3. Import and register in the DIAGRAMS dict in __main__.py
4. Run python scripts/forge_diagrams --lesson physics/NN to generate the PNG
5. Reference in the README: ![Description](assets/diagram_name.png)

Mermaid diagrams

For simulation loop architecture and broadphase/narrowphase pipelines:

```mermaid
flowchart LR
    A[Accumulate Forces] --> B[Integrate] --> C[Broadphase] --> D[Narrowphase] --> E[Resolve Contacts]
```

Example: Point Particles Lesson

Scenario: First physics lesson — teach integration and basic forces.

1. Scope: Position, velocity, acceleration, symplectic Euler, gravity, drag
2. Create: lessons/physics/01-point-particles/
3. Library: Create common/physics/forge_physics.h with ForgePhysicsParticle, forge_physics_integrate(), forge_physics_apply_gravity(), forge_physics_apply_drag()
4. Program: Drop 20 spheres from random heights, show them bouncing off a ground plane with restitution. Sphere colors map to velocity magnitude.
5. README: Explain Euler vs symplectic Euler, show energy drift comparison, derive the force accumulator pattern
6. Exercises: Change gravity direction, add wind force, compare explicit vs symplectic Euler stability

Example: Springs and Constraints Lesson

Scenario: Second lesson — teach spring forces and constraint solving.

1. Scope: Hooke's law, damped springs, distance constraints, chain systems
2. Create: lessons/physics/02-springs-and-constraints/
3. Library: Add forge_physics_spring_force(), forge_physics_constraint_distance() to the physics header
4. Program: A chain of spheres connected by springs hanging from a fixed point, swaying under gravity. A second chain using rigid distance constraints for comparison.
5. README: Derive Hooke's law, explain damping, show constraint projection
6. Exercises: Build a 2D cloth grid, add breakable springs, tune damping/stiffness

When NOT to Create a Physics Lesson

• The topic is covered by an existing physics lesson
• The concept is pure math with no simulation aspect (belongs in a math lesson)
• The concept is purely about rendering (belongs in a GPU lesson)
• The topic is about build systems or debugging (belongs in an engine lesson)
• The topic is too narrow for a full lesson (add to an existing lesson instead)

In these cases, update existing documentation or plan for later.

Tips

• Start with the simulation — Get the physics working with placeholder rendering first, then polish the visuals. A correct simulation with basic rendering is better than a beautiful scene with broken physics.
• Fixed timestep first — Set up the accumulator pattern before writing any physics code. Retrofitting fixed timestep is painful.
• Test with extremes — Run at very low and very high frame rates. The physics should behave identically. If it doesn't, something depends on frame rate.
• Show state — Consider displaying velocity, force, or energy values as text overlay or through color coding. Physics is easier to learn when you can see the numbers.
• Reset is essential — Physics demos often reach equilibrium quickly or objects leave the scene. The R key to reset keeps the demo useful.
• ASCII-only console output — Use only ASCII characters in printf output for cross-platform compatibility.