From 5210bd3d5503ac4eec3c98c39681b2fab4523157 Mon Sep 17 00:00:00 2001 From: Erik Date: Thu, 30 Apr 2026 13:21:21 +0200 Subject: [PATCH] =?UTF-8?q?docs(claude):=20communication=20style=20?= =?UTF-8?q?=E2=80=94=20plain=20language=20for=203D=20/=20physics=20/=20gra?= =?UTF-8?q?phics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Communication style" section after "How to operate" that documents how to discuss spatial / physics / animation / dat-format / protocol topics with the user. The user has asked repeatedly for plain-language framing of new concepts: name the idea in English first, then introduce the term of art; give units (degrees, meters) instead of raw floats; use analogies for spatial concepts (BSP = nested rooms, contact plane = imaginary floor, sphere sweep = rolling a ball, dot/cross products); walk through control flow frame-by-frame; flag terms of art the first time they appear. The goal is collaborative learning, not dumbed-down content. --- CLAUDE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 2ec702d..328264c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -112,6 +112,51 @@ a phase just landed, and move to the next todo item. always yes — keep going.** The single exception is visual verification; otherwise, act. +## Communication style + +The user is a strong systems / C# / network programmer but **less +practiced at 3D math, physics, graphics, and animation**. They want +to learn — they're not asking for dumbed-down content, but for +explanations that build understanding alongside the work. + +When discussing 3D / physics / graphics / animation / dat-format / +protocol-internals topics: + +- **Name the concept in plain language first**, then introduce the + term of art. "The angle of a slope (we call its straight-up + component `Normal.Z`)" rather than dropping `normal.Z = cos θ` + with no anchor. +- **Give units**: degrees, meters, cm — NOT raw floats. "FloorZ ≈ + 0.66 means slopes up to about 49° are walkable" rather than + "FloorZ = 0.66417414f". Floats are for the code; English is for + the conversation. +- **Use analogies for spatial concepts** when they fit. A BSP tree + is "a way of slicing space into nested rooms"; a contact plane is + "the imaginary floor under the player's feet"; a sphere sweep is + "rolling a ball forward through space and stopping it on contact"; + a cross product is "the direction perpendicular to two arrows"; + a dot product is "how aligned two arrows are (1 = same, 0 = + perpendicular, -1 = opposite)". +- **Don't pile on multiple new concepts in one paragraph.** If a + problem touches step-up AND step-down AND edge-slide AND + walkable-polygon tracking, walk through them one at a time, each + with what it does and why it exists. +- **Show the math when it matters, but explain it.** Don't just + drop a formula and move on; tag it with "what this means + geometrically". +- **Use frame-by-frame walk-throughs** for control-flow-heavy + physics: "frame N: player here, lands. Frame N+1: state checks…" + beats a function-call trace for understanding what's happening + in motion. +- **Flag terms of art** the first time they appear in a session, + even if they're sprinkled through code comments. "Broadphase", + "BSP", "step-up", "ContactPlane", "ValidateWalkable" — they + earn their meaning the first time you spell it out. + +The goal is collaborative learning. Don't simplify the content; just +make sure every term and number is grounded so the user can keep up +and build intuition over time. + ## Development workflow: grep named → decompile → verify → port **This is the mandatory workflow for implementing ANY AC-specific behavior.**