add architecture and authoring guideline docs
This commit is contained in:
David Allemang
497
docs/ARCHITECTURE.md
Normal file
497
docs/ARCHITECTURE.md
Normal file
@@ -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
|
||||
<!-- Without JS: plain text world definition -->
|
||||
<mc-diorama>
|
||||
<script type="text/mc-world">
|
||||
p 0 0 0 dropper...
|
||||
</script>
|
||||
</mc-diorama>
|
||||
|
||||
<!-- With JS: interactive canvas -->
|
||||
<mc-diorama>
|
||||
<canvas width="800" height="600"></canvas>
|
||||
</mc-diorama>
|
||||
```
|
||||
|
||||
### 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
|
||||
490
docs/AUTHORING_GUIDELINES.md
Normal file
490
docs/AUTHORING_GUIDELINES.md
Normal file
@@ -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 <core>
|
||||
== Entity IDs
|
||||
```
|
||||
|
||||
The `<core>` 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 `<name>` syntax:
|
||||
```typ
|
||||
== Entity IDs <core>
|
||||
== Stationary Item Optimization <singleplayer>
|
||||
== Paper Servers <paper>
|
||||
= Tilesets <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 <section-name>
|
||||
|
||||
== 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
|
||||
Reference in New Issue
Block a user