## FULL SPECIFICATION
# TDGS CONVENTIONS AND CONCEPTS - ForAI VERSION
# Document: Conventions and Concepts
# Badge: Foundational
# Status: Canonical
# Purpose: Defines organizational structure, terminology, and conventions for TDGS
# Canonical URL: https://tacticaldice.com/docs/tdgs/conventions
================================================================================
CORE PRINCIPLE: THREE EQUAL CONSTITUENCIES
================================================================================
TDGS is designed for three constituencies with EQUAL priority:
| Constituency | Description | Design Implication |
|--------------|----------------------------------|---------------------------------------|
| Humans | Tabletop players with dice/paper | Must be calculable without computers |
| Computers | VTTs, video games, bots, software| Must be deterministic and unambiguous |
| AI | Game runners, narrators, assistants | Must be learnable from docs alone |
DESIGN TEST - Every mechanic must pass ALL THREE:
1. Can a human calculate this at the table?
2. Can a computer execute this deterministically?
3. Can an AI learn and apply this from documentation?
If any answer is "no", the design needs revision.
================================================================================
NORMATIVE LANGUAGE DEFINITIONS
================================================================================
| Term | Meaning | Compliance |
|----------------|----------------------------------------|-------------------------------------|
| SHALL | Absolute requirement | Violating = not following TDGS |
| SHALL NOT | Absolute prohibition | Violating = not following TDGS |
| SHOULD | Strong recommendation | Deviation requires justification |
| SHOULD NOT | Strong discouragement | Deviation requires justification |
| MAY | Permission granted | Optional |
| MAY NOT | Permission not granted | Not forbidden, just not granted |
| WILL | Statement of fact/consequence | Not a command |
================================================================================
FOUR-LAYER ARCHITECTURE
================================================================================
Layer 4: Game Layer [DOWNSTREAM - not in repo]
↑ consumes
Layer 3: Content [DOWNSTREAM - not in repo]
↑ consumes
Layer 2: Extensions [IN REPO - MIT Licensed]
↑ consumes
Layer 1: Core [IN REPO - MIT Licensed - IMMUTABLE]
--------------------------------------------------------------------------------
LAYER 1: CORE
--------------------------------------------------------------------------------
Definition: Foundational mechanics everything depends on
Contents:
- Resolution mechanics
- Nine attributes
- Dice roles and usage
- Action economy
- Combat fundamentals
- Progression systems
- Entity structure
Rules:
- Core documents ARE numbered (Document 1, Document 2, etc.)
- Core documents carry the Core badge
- Core is IMMUTABLE from all other layers
- Changes require pull request (high bar, rarely accepted)
--------------------------------------------------------------------------------
LAYER 2: EXTENSIONS
--------------------------------------------------------------------------------
Definition: Mechanical modules that complement Core (specifications, not implementations)
Examples: Mounts and Vehicles, Mass Combat, Naval Warfare, Crafting Systems
Rules:
- Extensions SHALL NOT redefine Core mechanics
- Extensions SHALL NOT override Core mechanics
- Extensions MAY NOT contradict Core mechanics
- Extensions SHOULD provide new capabilities, not replacements
- Extension documents are NEVER numbered
- Extension documents carry the Extension badge
Official vs Community:
| Type | Location | License | Curation |
|-----------|-----------------|----------------------------|---------------------|
| Official | TDGS repository | MIT (mandatory) | TacticalDice curated|
| Community | External | Any (including proprietary)| Self-published |
--------------------------------------------------------------------------------
LAYER 3: CONTENT
--------------------------------------------------------------------------------
Definition: Concrete implementations using mechanics
Examples: Bestiaries, class definitions, race definitions, lore, items, spells
Rules:
- Content follows Core and Extension mechanics
- Content does NOT define new mechanics
- Content is DOWNSTREAM (not in TDGS repository)
--------------------------------------------------------------------------------
LAYER 4: GAME LAYER
--------------------------------------------------------------------------------
Definition: Implementation and user-facing products
Examples: User interfaces, character builders, VTTs, bots, playable games
Rules:
- Game Layer consumes Core, Extensions, and Content
- Game Layer MAY make UX decisions
- Game Layer SHALL NOT alter underlying mechanics
- Game Layer is DOWNSTREAM (not in TDGS repository)
================================================================================
DOCUMENT CLASSIFICATION
================================================================================
BADGES:
| Badge | Meaning | Numbered | In Repo |
|--------------|----------------------------------------------|----------|---------|
| Foundational | Project philosophy, structure, conventions | No | Yes |
| Core | Foundational mechanics, immutable downstream | Yes | Yes |
| Extension | Complementary mechanical modules | No | Yes |
| Supplemental | Reference material (e.g., Glossary) | No | Yes |
DOCUMENT NUMBERING RULES:
- ONLY Core documents receive numbers
- Format: "Document #: Title"
- TacticalDice assigns numbers upon acceptance
- Numbers are sequential
- Numbers are NEVER reused
- Numbered = Core (visual indicator)
DEPRECATION RULES:
- Deprecated documents are marked but retained
- Deprecating a Core document triggers MAJOR version change
- Previous versions remain available
================================================================================
VERSIONING
================================================================================
Pattern: {Major}.{Minor}.{Revision}
| Component | Meaning | Triggers |
|-----------|----------------------|---------------------------------------------------|
| Major | Breaking change | Core reimagined, Core doc deprecated, Extensions break |
| Minor | Non-breaking change | New mechanics, new Official Extensions, refinements |
| Revision | Non-mechanical fix | Spelling, grammar, formatting, wording |
Compatibility:
- Major change: downstream MAY break
- Minor change: downstream SHOULD continue working
- Revision: no impact
================================================================================
DOCUMENTATION STANDARDS
================================================================================
CANONICAL SOURCE:
https://tacticaldice.com/docs/tdgs is ALWAYS canonical.
- Repository contains same information
- Always link to TacticalDice.com, not repository
ForAI REQUIREMENT:
Every TDGS document SHALL have a ForAI companion.
- Naming: {documentname}forai
- Same canonical information
- Restructured for machine parseability
- No flavor text or narrative framing
- Consistent structure
- Front-loaded key information
- Minimal ambiguity
DATA INTERCHANGE FORMAT:
JSON is the default portable format.
Applies to:
- Character sheets
- Entity definitions
- Exported game state
- Interoperable data exchange
Does NOT apply to:
- Code files
- Documentation
- Internal storage (use whatever you want internally)
CROSS-REFERENCE RULES:
- Use document title or number (for Core)
- Link to canonical source (TacticalDice.com)
- Do not duplicate definitions; reference them
- Glossary aggregates FROM other documents (not the reverse)
================================================================================
MECHANICAL TRANSPARENCY PRINCIPLE
================================================================================
TDGS mechanics are intentionally transparent.
- Resolution formula is visible
- Math is explicit
- Outcomes follow from mechanics, not hidden judgment
- Players know what they need to roll
- Players know why they succeeded or failed
Extensions SHOULD maintain transparency.
Departing from transparency (hidden modifiers, secret rolls, GM-fiat mechanics)
is valid but against TDGS spirit.
================================================================================
LICENSING
================================================================================
ENGINE (Core, Extensions, Foundational, Supplemental):
MIT License
- Free to use, modify, redistribute
- Commercial use permitted
- Forking permitted
- No viral obligations
CHARACTERS (dice mascots):
NOT covered by MIT License
- Intellectual property of TacticalDice.com
- NOT released to public domain
- Reserved for official website only
Characters: Sir Critsalot, Decimancer, Flamey Eight-ball, Tetrahex the Obscure,
Nyxara Tidelight, Hundröd the Uncountable, Plushmaw the Unrollable,
Flippity Cent, His Rolliness the Sixth
Repository documents:
- SHALL NOT include character callouts
- SHALL NOT include character images
- SHALL NOT reference characters as if present
================================================================================
CONTRIBUTING RULES
================================================================================
PRE-CONTRIBUTION CHECKLIST:
1. Read Conventions document (this document)
2. Read Intent document
3. Identify target layer
4. Identify appropriate badge
CONTRIBUTION REQUIREMENTS:
1. Follow normative language (SHALL/SHOULD/MAY)
2. Respect layer boundaries
3. Create both human-readable AND ForAI versions
4. Use JSON for portable data
5. No character callouts in repository
CORE PULL REQUEST CRITERIA:
Core PRs face HIGH bar. Accepted when:
1. Genuine gap exists that Extensions cannot address
2. Change is backward compatible OR has clear migration path
3. Change has been discussed and vetted
4. Mathematical and systemic implications are understood
"I want it different" is NOT sufficient justification.
================================================================================
QUICK REFERENCE: WHAT GOES WHERE
================================================================================
| If creating... | Layer | Badge | Numbered | Repo |
|--------------------------|------------|--------------|----------|------|
| Fundamental mechanic | Core | Core | Yes | Yes |
| New mechanical module | Extension | Extension | No | Yes* |
| Project governance doc | N/A | Foundational | No | Yes |
| Reference material | N/A | Supplemental | No | Yes |
| Bestiary, classes, items | Content | N/A | No | No |
| Character builder, VTT | Game Layer | N/A | No | No |
* If Official Extension
================================================================================
QUICK REFERENCE: CONSTRAINT SUMMARY
================================================================================
ABSOLUTE (SHALL/SHALL NOT):
- Extensions SHALL NOT redefine Core mechanics
- Extensions SHALL NOT override Core mechanics
- Game Layer SHALL NOT alter underlying mechanics
- Every document SHALL have ForAI companion
- Repository documents SHALL NOT include character callouts/images
STRONG (SHOULD/SHOULD NOT):
- Extensions SHOULD provide new capabilities, not replacements
- Extensions SHOULD maintain mechanical transparency
- Downstream SHOULD continue working across Minor versions
PERMITTED (MAY):
- Extensions MAY NOT contradict Core mechanics (prohibition)
- Game Layer MAY make UX decisions
- Downstream MAY break on Major version change
- Community Extensions MAY use any license
================================================================================
END OF SPECIFICATION
================================================================================