From 9995d29421ec702b775c5b9af886a7876b3458a1 Mon Sep 17 00:00:00 2001 From: David Allemang Date: Thu, 10 Sep 2026 14:09:25 -0400 Subject: [PATCH] add architecture and authoring guideline docs --- docs/ARCHITECTURE.md | 497 +++++++++++++++++++++++++++++++++++ docs/AUTHORING_GUIDELINES.md | 490 ++++++++++++++++++++++++++++++++++ 2 files changed, 987 insertions(+) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/AUTHORING_GUIDELINES.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 00000000..43483446 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,497 @@ +# Architecture Documentation + +This document explains the architecture of the EID Wireless documentation system and its interactive diorama renderer. + +--- + +## Overview + +The EID Wireless documentation is a **text-first** technical resource that uses interactive 3D visualizations (dioramas) as *supplemental* learning tools. The core principle is: **readers should be able to understand the concepts without interactives, but gain deeper insight through them**. + +This is achieved through a hybrid architecture: + +1. **Typst** generates static HTML documents from `.typ` source files +2. **Custom JavaScript renderer** provides interactive dioramas embedded in those pages +3. **Vite** bundles everything together for development and production + +The dioramas are not the primary content—they're visual aids that appear *after* conceptual explanations and serve to reinforce understanding through visualization. + +--- + +## Architecture Goals + +### Primary Goal: Text-First Documentation + +The documentation system prioritizes readable, searchable, accessible text content. Interactive dioramas: + +- Are **optional** and **degrade gracefully** (pages work without JavaScript) +- Are **out-of-the-way** (don't interfere with reading flow) +- Are **supplemental** (don't contain core information that isn't in text) +- Are **mobile-friendly** (scrolling behavior is preserved by default) + +### Secondary Goals + +1. **Accurate Minecraft rendering** - Dioramas must faithfully represent block states, rotations, and redstone behavior +2. **Efficient rendering** - Multiple dioramas can appear on a single page; rendering must be performant +3. **Easy authoring** - Content creators should focus on concepts, not graphics programming +4. **Version independence** - Documentation should work across different Minecraft versions + +--- + +## System Architecture + +### High-Level Flow + +``` +Typst Source (.typ files) ──▶ HTML + JavaScript ──▶ Browser + │ + └─▶ Interactive Dioramas (WebGL) +``` + +### Components + +#### 1. Typst Document Generator + +**Role**: Converts `.typ` source files into HTML pages + +**Key Files**: +- `main.typ` - Main entry point, defines document structure +- `lib.typ` - Library functions (`diorama()`, `callout()`, etc.) +- `content/*.typ` - Documentation chapters +- `typst.toml` - Package metadata + +**Responsibilities**: +- Compile `.typ` files into HTML using `tinymist` language server +- Embed interactive elements via `#show` directives +- Generate navigation between pages + +**Key Pattern** - Diorama Embedding: + +```typ +#show raw.where(lang: "mc-diorama"): it => diorama( + orbit: true, + pan: true, + autoplay: true, + it.text, +) +``` + +This directive tells Typst to: +1. Find all `mc-diorama` code blocks +2. Wrap them in the `diorama()` function +3. Pass block content as the world definition + +#### 2. World Definition System + +**Role**: Defines Minecraft scenes using a timeline-based domain-specific language + +**Format**: +``` +p x y z block_type properties +t time +``` + +Where: +- `p` places or modifies blocks at coordinates +- `t` advances the timeline +- Properties are `key=value` pairs (e.g., `facing=east`, `powered=true`) + +**Example**: +``` +p 0 0 0 dropper facing=up triggered=false +p 0 1 0 dropper facing=up triggered=false +t 2 +p 0 0 0 triggered=true +t 4 +p 0 0 0 triggered=false +``` + +This format is designed to be: +- **Human-readable** - Easy to write and debug +- **Concise** - Minimal boilerplate +- **Timeline-aware** - Changes occur at specific game ticks + +#### 3. WebGL Renderer (Engine) + +**Role**: Renders Minecraft blocks as 3D models using WebGL + +**Key Files**: +- `src/engine.js` - Main renderer class +- `src/world.js` - World state management +- `src/diorama.js` - Camera and view management +- `src/math.js` - Matrix operations (orthographic projection, look-at, etc.) + +**Architecture**: + +``` +Engine (singleton) +├── Dioramas (multiple per page) +│ ├── Canvas (2D context for offscreen rendering) +│ └── Frame (world timeline state) +└── Resources (blockstates, models, textures) + ├── Cache (async resource loading) + ├── Blockstate Handler (parses JSON blockstate definitions) + ├── Model Handler (builds geometry from models) + └── Texture Handler (atlas textures into single canvas) +``` + +**Key Features**: +- **Instanced rendering** - Thousands of blocks rendered efficiently +- **Lazy updates** - Only re-renders when content changes +- **View culling** - Skips rendering for off-screen dioramas +- **Texture atlasing** - Packs all textures into single texture for batch rendering + +#### 4. Controller System + +**Role**: Handles user interaction with dioramas + +**Key Files**: +- `src/controller.js` - SpacetimeController class +- `src/components.js` - Custom HTML elements + +**Features**: +- **Orbit controls** - Rotate view (left drag) +- **Pan controls** - Move view (middle drag or shift+left) +- **Zoom controls** - Scale view (right drag or ctrl+left) +- **Timeline autoplay** - Auto-play animations with configurable speed +- **Mobile support** - Touch gestures with scroll delegation +- **State preservation** - Camera position and timeline state can be reset + +**Mobile-Specific Behavior**: +- Default browser scroll is preserved (diagram doesn't capture scroll) +- Touch interaction requires deliberate engagement (200ms timeout) +- 1-finger touch: orbit (don't interfere with scroll) +- 2-finger touch: pan + zoom (pinch gesture) + +#### 5. Build System + +**Role**: Integrates Typst output with JavaScript rendering + +**Key Files**: +- `vite.config.js` - Vite configuration +- `mise.toml` - Development tool configuration +- `dist/` - Production output directory + +**Workflow**: + +```bash +# Development +mise run dev # Runs Vite dev server + Typst watch + +# Build +mise run build # Compile Typst + bundle with Vite +``` + +**Vite Configuration**: +- `root: .typ-bundle` - Typst-generated HTML is the Vite root +- `publicDir: public` - Static assets served from Minecraft assets +- Alias `/src` → `src/` - JavaScript modules accessible from HTML +- Watch mode monitors both `.typ` and `src/**/*` files + +--- + +## Data Flow + +### 1. Document Compilation + +``` +Typst Source (.typ) + ↓ (tinymist) +HTML + Scripts + ↓ (Vite bundling) +dist/index.html +``` + +### 2. World Parsing + +``` +mc-diorama Code Block + ↓ (World constructor) +World Object +├── events[] - Timeline events (changes at each tick) +├── initialState - Block state at t=0 +└── labels - Named timeline positions +``` + +### 3. Frame Playback + +``` +World Object + ↓ (WorldFrame) +Frame Object +├── blocks[] - Current block state +├── currentTime - Timeline position +└── listeners[] - Callbacks on state change +``` + +### 4. Rendering Pipeline + +``` +Frame State Change + ↓ +Engine.updateAll() +├── Parse blocks → Blockstates → Models +├── Build geometry (positions, normals, UVs) +├── Update texture atlas +└── Create instanced meshes (VBOs) + +Frame State Change (again) + ↓ +Engine.render() +├── Check visibility (cull off-screen dioramas) +├── Update camera matrices (orthographic projection) +├── Draw instanced meshes (WebGL) +└── Copy to 2D canvas (for HTML display) +``` + +### 5. Resource Loading + +``` +Request Blockstate/Model/Texture + ↓ +Cache.getAsync() +├── Check if already loading → return promise +├── Check if already loaded → return data +└── Kick off fetch + prepare fallback + +Fetch Complete + ↓ +Handler.process() +├── Parse JSON (blockstate/model) +├── Build geometry (model) +└── Return structured data + ↓ +Cache.onResolve() → Engine.requestUpdate() +``` + +--- + +## User Experience: What Users Actually See + +Dioramas appear as interactive 3D diagrams within the documentation: + +``` +┌─────────────────────────────────────┐ +│ Text explanation of redstone... │ +│ (this is the primary content) │ +├─────────────────────────────────────┤ +│ ┌───────────────────────────────┐ │ +│ │ [Diorama: 3D interactive │ │ +│ │ view of the mechanism] │ │ +│ │ │ │ +│ │ (click/drag to interact) │ │ +│ └───────────────────────────────┘ │ +│ Caption: "Figure 1: Mechanism" │ +└─────────────────────────────────────┘ +``` + +**Key UX Principles**: + +1. **Dioramas are after the text** - Readers understand conceptually first, then visualize +2. **Dioramas don't steal scroll** - Default browser scroll works; interaction requires deliberate action +3. **Mobile-first interaction** - Touch gestures don't interfere with page navigation +4. **Progressive enhancement** - Pages work without JS; dioramas add value when JS is available + +### Camera System + +Dioramas use **orthographic projection** (not perspective) because: + +1. Redstone mechanisms are small and detailed +2. Orthographic preserves proportions +3. Better for technical diagrams +4. Easier to measure distances + +**Camera Parameters**: +- `target` - Point camera looks at (world coordinates) +- `radius` - Distance from target +- `theta` - Horizontal rotation angle (degrees) +- `phi` - Vertical rotation angle (degrees) + +**Matrix Calculation**: +1. Convert spherical coordinates to Cartesian (eye position) +2. Calculate view direction and up vector +3. Build view matrix via `mat4LookAt()` +4. Build orthographic projection matrix based on radius and aspect ratio +5. Combine: `viewProj = projection × view` + +### Instanced Rendering + +Each unique block variant gets its own instanced mesh: + +``` +Geometry (positions, normals, UVs, tints, shades) + ↓ +Instance Data +├── Matrix[] (16 floats each) - World transformation +└── Color[] (3 floats each) - Redstone power tint + ↓ +GPU Buffer (VBO) + ↓ +DrawElementsInstanced() +``` + +This allows thousands of blocks to be rendered in a single draw call. + +### Texture Atlasing + +All block textures are packed into a single canvas: + +``` +16×16px blocks + ↓ +Atlas Canvas (256×256px default) +├── Cell 0: block_0.png +├── Cell 1: block_1.png +├── Cell 2: block_2.png +└── ... + ↓ +UV Map +├── u, v (cell position) +└── du, dv (cell size) +``` + +Texture loading is **asynchronous** but **synchronous fallback** is provided: +- Renderer immediately gets UV coordinates +- Texture data loads in background +- Fallback texture (black silhouette) shown until loaded + +--- + +## Interactive Element Design + +### Accessibility First + +Dioramas must work without JavaScript: + +```html + + + + + + + + + +``` + +### Performance Optimizations + +1. **Lazy rendering** - Only update when content changes +2. **Visibility culling** - Skip off-screen dioramas +3. **State preservation** - Only rebuild meshes when blocks change +4. **Texture batching** - Single texture bind for all blocks +5. **Instanced drawing** - One draw call per block type + +### Mobile-First Interaction + +**Touch Handling**: +- 200ms delay before engaging (allows scroll detection) +- 1-finger: orbit (doesn't interfere with page scroll) +- 2-finger: pan + zoom (pinch gesture) +- Touch doesn't block page scroll unless clearly interacting + +**Scroll Delegation**: +```javascript +canvas.addEventListener('touchstart', e => { + // Check if user is trying to scroll + if (maxTouchDistance < 10px) { + // Let browser handle scroll + return; + } + // Engage diorama interaction + e.preventDefault(); +}); +``` + +--- + +## Extensibility + +### Adding New Block Types + +1. **Blockstate JSON** - Define block variants in `public/assets/minecraft/blockstates/` +2. **Model JSON** - Define geometry in `public/assets/minecraft/models/` +3. **Texture PNG** - Add texture image in `public/assets/minecraft/textures/` + +The system automatically discovers and loads these assets. + +### Adding New Diorama Features + +The controller system is designed for easy extension: + +```javascript +class SpacetimeController { + constructor(diorama, options = {}) { + this.opts = {orbit: true, pan: true, zoom: true, ...options}; + // Add new options here + } +} +``` + +New features can be added as optional behaviors without breaking existing dioramas. + +--- + +## Development Workflow + +### Running Locally + +```bash +mise run dev +# Opens browser at localhost:5173 +# Automatically reloads on changes to .typ or src/**/* +``` + +### Building for Production + +```bash +mise run build +# Compiles Typst to .typ-bundle/ +# Bundles with Vite to dist/ +``` + +### Debugging + +**Enable debug redraw**: +```javascript +window.mcEngine.debug_redraw = true; +// Highlights regions that are being redrawn +``` + +**Check resource loading**: +```javascript +window.mcEngine.cache.data +// Shows all loaded resources +``` + +**Inspect frame state**: +```javascript +const frame = document.querySelector('mc-diorama').frame; +console.log(frame.blocks, frame.currentTime); +``` + +--- + +## Future Architecture Changes + +The JavaScript API is intentionally unstable. Planned changes: + +1. **Component system** - Move from custom elements to framework components +2. **WebAssembly rendering** - Potential Rust/WASM renderer for better performance +3. **TypeScript migration** - Improve type safety and IDE support +4. **Animation system** - More sophisticated timeline interpolation +5. **Shader effects** - Enhanced visual feedback (glows, particles, etc.) + +These changes won't break the Typst authoring experience—the diorama content format will remain the same. + +--- + +## References + +- Typst documentation: https://typst.app/docs +- WebGL2 documentation: https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API +- Minecraft Java Edition documentation: https://minecraft.wiki/w/Java_Edition +- Instanced rendering: https://learnopengl.com/Advanced-OpenGL/Instancing diff --git a/docs/AUTHORING_GUIDELINES.md b/docs/AUTHORING_GUIDELINES.md new file mode 100644 index 00000000..4e891cbd --- /dev/null +++ b/docs/AUTHORING_GUIDELINES.md @@ -0,0 +1,490 @@ +# Typst Documentation Authoring Guidelines + +This document provides comprehensive authoring guidelines for the EID Wireless documentation written in Typst. + +--- + +## 1. Voice and Tone + +### General Approach +- **Technical but approachable**: Explain complex technical concepts clearly without oversimplifying +- **Use examples and analogies**: Concrete examples help readers understand abstract concepts +- **Direct and conversational**: Use second-person perspective and active voice when appropriate +- **Confident and authoritative**: The documentation presents established facts and proven principles + +### Voice Characteristics +```typ +// Example of technical but approachable tone (from core.typ:25-27) +#callout(kind: "tip", label: "Key Point")[ + Stationary items only begin to fall when their $"age" + "id"$ is a multiple of $4$. +] +``` + +The documentation explains technical details clearly: +- Uses precise terminology ("stationary items," "mod 4 cycle") +- Provides context and explanation for why things work +- Avoids jargon without explanation + +### Examples from the Documentation +The documentation frequently uses: +1. **Direct explanation**: "Recall that *any* entity spawning will increment the ID counter" +2. **Examples with concrete scenarios**: Step-by-step walkthroughs of entity spawning +3. **Mathematical reasoning**: Clear derivation of relationships with mod arithmetic +4. **Practical implications**: "Therefore $B$ falls at time $t=2$" + +--- + +## 2. Formatting Conventions + +### Mathematical Notation +- Use `$...$` for inline math: `$"age"_(A, 1) = "age"_(A, 0) + 1$` +- Use `&` for alignment in multi-line equations +- Use `(mod N)` notation for modular arithmetic: `$... equiv 0 &(mod 4)$` + +**Important**: The documentation uses a specific notation for modular arithmetic: +```typ +$ "age"_(A, 0) + 1 + "id"_A & equiv 0 (mod 4) $ +``` + +### Code Blocks +- Use triple backticks with language specifier: ```` ```mc-diorama` `` +- The documentation defines a custom diorama format for Minecraft diagrams +- Java code blocks use: ```` ```java ```` + +**Example from core.typ:41-67**: +```java +public class ItemEntity extends Entity { + public void tick() { + ... + if (this.onGround() && !(this.getDeltaMovement().horizontalDistanceSqr() > (double)1.0E-5F) && (this.tickCount + this.getId()) % 4 != 0) { + ... + } else { + this.move(MoverType.SELF, this.getDeltaMovement()); + ... + } + ... + } +} +``` + +### Block References +- Use `@symbol` syntax to reference sections: `@singleplayer`, `@paper`, `@tilesets` +- Use `@block-priority`, `@block-delay`, `@observer-bug` for subsections + +### Section Headers +- Use `=` for level 1 headings (chapters): `= Core Mechanics` +- Use `==` for level 2 headings (sections): `== Entity IDs` +- Use `===` for level 3 headings (subsections): `=== Daylight Detector` + +**Example from core.typ:3**: +```typ += Core Mechanics +== Entity IDs +``` + +The `` syntax creates an anchor/ID for the section. + +--- + +## 3. Interactive Elements (Dioramas) + +### What is a Diorama? +A diorama is an interactive visualization of Minecraft redstone mechanisms. The documentation uses custom `mc-diorama` blocks that render as interactive HTML elements. + +### Integration Syntax +Dioramas are integrated using the `#show` directive in `lib.typ`: + +```typ +#show raw.where(lang: "mc-diorama"): it => diorama( + autoplay: true, + loop: true, + radius: 5, + theta: 25, + phi: 25, + it.text, +) +``` + +This directive tells Typst to: +1. Find all blocks with language `mc-diorama` +2. Wrap them in the `diorama()` function +3. Pass the block content as `it.text` + +### Diorama Parameters +Common parameters include: +- `autoplay: true` - Start animation automatically +- `loop: true` - Repeat animation when finished +- `orbit: true` - Enable orbit camera controls +- `pan: true` - Enable pan camera controls +- `zoom: true` - Enable zoom controls +- `radius`, `theta`, `phi` - Camera position +- `speed` - Animation speed + +**Example from tilesets.typ:15-23**: +```typ +#show raw.where(lang: "mc-diorama"): it => diorama( + orbit: true, + pan: true, + zoom: true, + autoplay: true, + theta: 160, + phi: 20, + it.text, +) +``` + +### Diorama Content Format +Diorama content uses a custom format: +``` +p x y z block_type properties +t time +``` + +Where: +- `p` = place/modify a block at coordinates +- `t` = advance time to specified tick +- Properties are space-separated key=value pairs + +**Example from design.typ:17-49**: +``` +p 0 0 0 smooth_stone_slab type=top +p 0 1 0 daylight_detector inverted=true power=1 +p 0 2 0 piston facing=east extended=false +t 0 +p 0 2 0 extended=true +t 1 +p 0.5 2 0 piston_head facing=east short=true type=normal +``` + +### Timeline Format +The diorama uses a timeline-based animation system: +- `t N` advances the timeline to tick N +- Changes between ticks are interpolated +- Multiple changes can be made at the same tick + +--- + +## 4. Stylistic Patterns + +### Callouts +Callouts are defined in `lib.typ:1-10` and used extensively throughout the documentation: + +```typ +#let callout(body, kind: none, label: none, outlined: false) = { + html.section( + class: ("callout", kind), + context { + let level = counter(heading).get().len() + 1 + heading(label + ":", level: level, numbering: none, outlined: outlined) + body + }, + ) +} +``` + +#### Types of Callouts +1. **Tip**: `#tip[Content]` - Helpful suggestions or insights +2. **Note**: `#note[Content]` - Important information or clarifications +3. **Warning**: `#warn[Content]` - Critical warnings or cautions +4. **Todo**: `#todo[label, body]` - Notes for future work + +### Example and Solution Blocks +These are currently implemented as TODO callouts but are planned to be proper elements: + +```typ +#let example(body) = todo("example", body) +#let solution(body) = todo("solution", body) +``` + +**Example from core.typ:83-116**: +```typ +#example[ + For example, suppose we spawn an item $A$, then 2 game ticks later we spawn an item $B$... + + #solution[ + To simplify the arithmetic, orient everything around $t=0$... + ] +] +``` + +### Details Block +The `details` function is defined but commented out, suggesting it's planned for expansion: + +```typ +#let details(body, label: none) = { + todo(label, body) + // html.details({ + // if label != none { + // html.summary(label) + // } + // body + // }) +} +``` + +### HTML Integration +The documentation uses HTML elements for interactive components: + +**From design.typ:128-135**: +```typ +#html.div(id: "atlas-container", style: "position: fixed; left: 0; top: 0; border 1px solid white;") +#html.script( + " +document.onreadystatechange = () => { +document.getElementById('atlas-container')?.appendChild(window.mcEngine.atlas.canvas) +} +", +) +``` + +--- + +## 5. Structuring Technical Explanations + +### Problem → Solution Format +The documentation frequently follows this pattern: +1. Present the problem or phenomenon +2. Explain the underlying mechanism +3. Show the mathematical reasoning +4. Provide concrete examples +5. Draw conclusions + +**Example from core.typ:77-227**: +``` +== Observable Drop Delay +[Problem] We can't control absolute entity ID but can compare them +[Explanation] Use reference items to predict behavior +[Example 1] Simple two-item comparison with math derivation +[Example 2] Four-item scenario showing pattern recognition +[Example 3] Broken pattern analysis to determine entity spawns +``` + +### Mathematical Explanations +When explaining mathematics, the documentation uses: + +1. **State the relation**: "$"age"_(A, 0) + 1 + "id"_A equiv 0 (mod 4)$" +2. **Substitute known values**: "Item $A$ has ID before $B$, so $"id"_A = "id"_B - 1$" +3. **Show derivation**: Multi-line equation with alignment +4. **State conclusion**: "*$A$ must fall at $t=0$.*" + +**Example from core.typ:107-116**: +``` +So take the relation for $A$ and substitute in these values for $B$. + +$ + "age"_(A, 0) + 1 + "id"_A & equiv 0 (mod 4) \ + "age"_(B, 0) + 2 + 1 + "id"_B - 1 & equiv 0 (mod 4) \ + "age"_(B, 0) + 2 + "id"_B & equiv 0 (mod 4) \ +$ + +Compare with the relation for $B$ and we see that $x=2$. + +#callout(kind: "tip", label: "Therefore:")[$B$ falls at time $t=2$. +] +``` + +### Java Code Documentation +When showing Java code: + +1. **Include only relevant sections**: Don't show entire classes, just the important parts +2. **Add context with notes**: Use `#note[]` to explain what code does +3. **Highlight key lines**: The documentation shows full code but focuses reader attention + +**Example from core.typ:38-52**: +```typ +#note[ `onGround` is only ever updated via `move`, and this branch is the *only* place that + `ItemEntity.move` is called. `tickCount` is the item's age. ] + +```java +public class ItemEntity extends Entity { + public void tick() { + ... + if (this.onGround() && !(this.getDeltaMovement().horizontalDistanceSqr() > (double)1.0E-5F) && (this.tickCount + this.getId()) % 4 != 0) { + ... + } else { + this.move(MoverType.SELF, this.getDeltaMovement()); + ... + } + ... + } +} +``` +``` + +--- + +## 6. Relationship Between Text and Interactive Visualizations + +### Dioramas as Explanatory Tools +Dioramas are not just decorative—they are integral to understanding: + +1. **Before reading, see the phenomenon**: Dioramas show what happens first +2. **Then read the explanation**: Text explains why it happens +3. **Then verify understanding**: Readers can manipulate the diorama + +**Pattern from tilesets.typ:15-56**: +```typ +#show raw.where(lang: "mc-diorama"): it => diorama(...) + +```mc-diorama +p 0 -1 0 smooth_stone_slab type=top +p 1 -1 0 smooth_stone_slab type=top +... (animation showing tile sequence) +t 20 +p 0 0 0 +``` +``` + +The diorama appears *before* the textual explanation, allowing readers to observe first. + +### Text Supporting Visualization +Text always complements the diorama by: + +1. **Explaining what to look for**: "Note how the redstone signal propagates in order" +2. **Providing context**: "This 4gt tileset demonstrates binary encoding" +3. **Giving the mathematical basis**: "We identify higher priority with 0, lower with 1" + +### Multiple Perspectives +Complex concepts are shown from multiple angles: + +**Example: Tilesets in tilesets.typ** +1. **Full diorama** showing the complete system (lines 15-56) +2. **Numeric representation** showing the encoding (lines 254-263) +3. **Abstract diagram** showing the bit pattern (line 268) +4. **Another diorama** showing arbitrary values (lines 270-297) + +This multi-modal approach helps different learning styles. + +### Interactive vs. Static +The documentation uses: +- **Autoplay loops** for demonstrating processes: `autoplay: true, loop: true` +- **Manual control** for exploration: `orbit: true, pan: true, zoom: true` +- **Static cameras** for focused attention: `orbit: false` + +--- + +## 7. Additional Conventions + +### File Organization +- Content files are in `/content/` directory +- Library definitions in `/lib.typ` +- Main document in `/main.typ` +- Each content file corresponds to a web page + +### Linking +External links use `#link("URL")[text]`: +```typ +#link("https://youtu.be/81OV1BltMQ8")[iPlayGames's Wireless Masterclass] +#link("https://minecraft.wiki/w/Entity#Types_of_entities")[The Minecraft Wiki] +``` + +### Cross-References +Use `@symbol` for internal references: +```typ +See @singleplayer for details. +See @paper for details. +See @tilesets for details. +``` + +### TODO System +The documentation uses `#todo[label, body]` for planning: +```typ +#todo["Network Protocol" is inaccurate] +#todo[Singleplayer patch links][figure out exact version compatibility list.] +``` + +### Block References +Special section anchors use `` syntax: +```typ +== Entity IDs +== Stationary Item Optimization +== Paper Servers += Tilesets +``` + +--- + +## 8. Best Practices for Authors + +### When Writing New Content +1. **Start with a diorama** showing the phenomenon or system +2. **Explain the mechanism** with clear, concise language +3. **Provide mathematical justification** when appropriate +4. **Give concrete examples** with step-by-step reasoning +5. **Use callouts** for key takeaways and warnings +6. **Reference existing sections** rather than repeating information + +### When Creating Dioramas +1. **Use autoplay for demonstrations** of recurring patterns +2. **Enable orbit/pan/zoom for complex systems** readers should explore +3. **Keep timelines explicit** with clear `t N` markers +4. **Show before/after states** to demonstrate changes +5. **Use appropriate scaling**—don't overcrowd the view + +### Mathematical Writing +1. **Define all variables** before using them +2. **Show derivation steps** clearly with alignment +3. **Use consistent notation** throughout +4. **Explain the mod arithmetic** thoroughly +5. **Connect math to implementation** with code examples + +--- + +## 9. Template for New Sections + +Here's a recommended template for new documentation sections: + +```typ +#show raw.where(lang: "mc-diorama"): it => diorama( + autoplay: true, + loop: true, + radius: 5, + theta: 25, + phi: 25, + it.text, +) + += Section Title + +== subsection + +```mc-diorama +p 0 0 0 block_type +p 0 1 0 another_block +t 0 +p 0 0 0 changed_block +t 10 +p 0 0 0 +``` + +Explanation of what's happening, why it matters, and how it works. + +#example[ + Concrete example with step-by-step walkthrough. + + #solution[ + Solution or explanation of the example. + ] +] + +#callout(kind: "tip", label: "Key Insight")[ + Important takeaway or rule of thumb. +] +``` + +--- + +## 10. References + +These guidelines are based on analysis of the following files: +- `/content/core.typ` - Core mechanics with examples +- `/content/interference.typ` - Interference sources and solutions +- `/content/tilesets.typ` - Tileset patterns and examples +- `/content/block-event-delay.typ` - BED mechanisms +- `/content/design.typ` - Design tips and dioramas +- `/content/channels.typ` - Channel management (outline only) +- `/content/network.typ` - Network protocols (outline only) +- `/content/bulk.typ` - Bulk transport (outline only) +- `/content/data-protocols.typ` - Data protocols (outline only) +- `/lib.typ` - Library functions and callout definitions +- `/main.typ` - Main document structure