# Dev Physics Lesson > Add a physics lesson — particle dynamics, rigid bodies, collisions, constraints, rendered with SDL GPU - **Type:** Skill - **Install:** `agentstack add skill-nebulavenus-forge-gpu-dev-physics-lesson` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Nebulavenus](https://agentstack.voostack.com/s/nebulavenus) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Zlib - **Upstream author:** [Nebulavenus](https://github.com/Nebulavenus) - **Source:** https://github.com/Nebulavenus/forge-gpu/tree/main/.claude/skills/dev-physics-lesson ## Install ```sh agentstack add skill-nebulavenus-forge-gpu-dev-physics-lesson ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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: ```text 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) 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 `` — never include ``, ``, or `` 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):** ```c /* 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:** ```c #ifndef FORGE_PHYSICS_H #define FORGE_PHYSICS_H #include #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." ```c /* 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. ```c /* 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. ```c /* 10000 steps of a bouncing ball — energy must not grow unboundedly */ for (int i = 0; i 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: ```c /* 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/`. ```c #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 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:** ```c /* * 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 #include #include #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 ───────────────────────────────── … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Nebulavenus](https://github.com/Nebulavenus) - **Source:** [Nebulavenus/forge-gpu](https://github.com/Nebulavenus/forge-gpu) - **License:** Zlib Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-nebulavenus-forge-gpu-dev-physics-lesson - Seller: https://agentstack.voostack.com/s/nebulavenus - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.