# EmberLite

> EmberLite (https://emberlite.net) is a client-side virtual tabletop (VTT) and procedural generation workbench for tabletop RPGs. It operates 100% local-first in the browser with Bring Your Own Storage (BYOS), zero developer-hosted backends, and deterministic seeded pseudo-random algorithms.

## Quick Links for AI & LLM Systems
- [EmberLite Full Specification](https://emberlite.net/llms-full.txt): Complete grammar, schemas, and API documentation for LLMs.
- [EmberLite Language Spec (.el)](https://emberlite.net/docs/EMBERLITE_LANGUAGE_SPEC.md): Plain text markdown format for tables, cards, and cue chains.
- [Templates Manifest](https://emberlite.net/templates/manifest.json): Static JSON catalog of human-authored TTRPG modules and character sheets.
- [Model Context Protocol Specification](https://emberlite.net/.well-known/mcp.json): Machine-readable MCP tools definition.
- [GitHub Repository](https://github.com/lynn0702/emberlite): Source code and deployment pipeline.

## Core Concepts
- **Sparks**: Atomic random generation cues (weighted tables, dice ranges, cue chains) rendered as interactive SVG pills.
- **Shapes**: Structured interactive sheets (Character sheets, Hex flower maps, Confrontation trackers) authored in plain Markdown.
- **Blocks**: Modular action rollers and dice engines (Cortex Choose-2, polyhedral, d6 pool).
- **Deterministic Seeded PRNG**: All tables, dice rolls, and procedural maps use weighted pseudo-random algorithms driven by an explicit seed for 100% reproducible results.

## How to Author Content for EmberLite
LLMs and external tools can generate plain text `.el` (EmberLite Language) files. EmberLite automatically parses them into rollable canvas cards.

### Minimal `.el` Table Example
```markdown
# EmberLite Sparks Dataset

## Table: Wilderness Encounters
- **Category:** Exploration
- **Source:** https://farirpgs.com/
- **Default Chain:** Weather

| Result | Weight | Dice | Chain | Notes |
| --- | --- | --- | --- | --- |
| Abandoned Watchtower | 2 | 1-2 | Clue | Stone structure |
| Wandering Patrol | 1 | 3-4 | Confrontation | 2d6 guards |
| Ancient Monolith | 1 | 5-6 | Lore | Glowing runes |
```

### Minimal Shape Template Example
```markdown
# Shape: NPC Sheet
- **ID:** custom_npc
- **System:** TorchLite
- **Category:** character
- **Kind:** shape
- **Color:** #8b5cf6
- **Icon:** User

## Section: Core Info
- **Field:** name | Name | text | Kaelen Shadow-Walker
- **Field:** role | Role | select | Scout | options: Warrior, Scout, Mystic
- **Field:** grit | Grit | number | 4
```

## Deep Linking & URL Importing
You can provide users with direct clickable links that automatically import content onto their EmberLite canvas:
- Remote URL import: `https://emberlite.net/spark?importUrl=<RAW_TEXT_URL>`
- Inline `.el` text import: `https://emberlite.net/spark?el=<URI_ENCODED_OR_BASE64_EL_TEXT>`
- Open specific template: `https://emberlite.net/spark?template=<TEMPLATE_ID>`