Skip to main content

Template System Deep Dive

Unlock the full power of BeatBandit's sophisticated template architecture. Understanding how templates work will help you customize your workflow and create professional screenplay structures.

Template Architecture Overview​

BeatBandit uses a hierarchical template system that separates structure from content, allowing for infinite customization and professional flexibility.

The Three-Layer Architecture​

Layer 1: Card Definitions (Atomic Building Blocks)​

Individual card definitions stored in src/templates/movie/cards/*.json:

  • Atomic units of story content
  • Field structure definitions
  • AI instruction templates
  • User interface configuration

Layer 2: Stage Definitions (Orchestration)​

Stage configurations in src/templates/movie/stages/*.json:

  • Card organization and grouping
  • Workflow sequencing
  • Stage-specific guidance
  • Context relationships

Layer 3: Project Materialization (Runtime)​

Database records created from templates:

  • Dynamic content storage
  • Version control system
  • User customization preservation
  • Collaboration support

Card Definition Deep Dive​

Understanding card definitions unlocks advanced customization possibilities.

Card Definition Structure​

{
  "code": "10.10.10",
  "title": "Protagonist Definition",
  "fields": {
    "name": "Character name",
    "role": "Story function",
    "description": "Physical and personality traits",
    "backstory": "Character history and motivation",
    "arc": "Character transformation journey"
  },
  "info": {
    "description": "Define your story's main character",
    "placeholder": "Enter protagonist details...",
    "guidance": "Focus on what drives this character"
  },
  "llm_instructions": {
    "context": "This is the story's main character",
    "style": "Create a compelling, three-dimensional character",
    "constraints": "Maintain consistency with story genre and tone",
    "suggestions": "Focus on motivation, conflict, and growth"
  }
}

Field Type Intelligence​

Single-Field Cards

  • Simple structure: One main content area
  • Direct editing: Streamlined interface
  • Fast processing: Minimal overhead
  • Examples: Logline, theme, simple beats

Multi-Field Cards

  • Complex structure: Multiple organized sections
  • Structured editing: Field-specific interfaces
  • Rich validation: Content consistency checking
  • Examples: Characters, detailed scenes, locations

Dynamic Cards

  • Runtime creation: Generated based on user actions
  • Position awareness: Automatic sequencing
  • Relationship mapping: Connections to other cards
  • Examples: Scene cards, beat sequences

Stage Definition Mastery​

Stages orchestrate cards into meaningful workflows.

Stage Configuration Elements​

Primary Card Codes Cards that belong to this specific stage:

"primary_card_codes": [
  "10.10.10",  // Protagonist
  "10.10.20",  // Antagonist
  "10.10.30"   // Supporting characters
]

Linked Card Codes Related cards from other stages for context:

"linked_card_codes": [
  "05.10.10",  // Logline for character consistency
  "15.20.*",   // Act 2 beats for character development
  "30.*"       // All Act 3 cards for arc completion
]

Card Templates Dynamic card creation rules:

"card_template": {
  "prefix": "25.30",
  "type": "scene",
  "auto_numbering": true,
  "position_hints": true
}

Advanced Stage Strategies​

Context Optimization Design stages for efficient context loading:

  • Focused scope: Related cards only
  • Smart linking: Strategic cross-stage references
  • Token efficiency: Manageable context size
  • AI performance: Optimized for specific tasks

Workflow Design Create logical progression through stages:

  • Dependencies: Required previous stage completion
  • Parallel paths: Independent development tracks
  • Iteration loops: Return to previous stages for refinement
  • Quality gates: Review points before progression

Template Customization Techniques​

Creating Custom Card Types​

Identify Your Needs

  • Missing content types in standard templates
  • Genre-specific requirements (sci-fi, horror, comedy)
  • Personal workflow preferences
  • Project-specific elements

Design Custom Cards

  1. Define the purpose: What story element does this capture?
  2. Structure the fields: What information is needed?
  3. Create AI instructions: How should AI assist with this content?
  4. Design the interface: How will users interact with it?

Example: Custom "Technology" Card for Sci-Fi

{
  "code": "12.50.10",
  "title": "Technology Element",
  "fields": {
    "name": "Technology name",
    "function": "What it does",
    "limitations": "What it can't do",
    "impact": "How it affects the story",
    "rules": "Internal logic and consistency"
  },
  "llm_instructions": {
    "context": "Science fiction technology element",
    "style": "Maintain scientific plausibility",
    "constraints": "Consistent with established story rules"
  }
}

Building Custom Stages​

Stage Design Principles

  • Single focus: Each stage serves one primary purpose
  • Logical grouping: Related cards work together
  • Clear boundaries: Distinct from other stages
  • Workflow integration: Fits into overall development process

Custom Stage Example: "World Building" for Fantasy

{
  "name": "World Building",
  "description": "Establish the fantasy world and its rules",
  "primary_card_codes": [
    "11.10.10",  // World Overview
    "11.20.10",  // Magic System
    "11.30.10",  // Geography
    "11.40.10",  // Cultures
    "11.50.10"   // History
  ],
  "linked_card_codes": [
    "10.10.*",   // All characters for world consistency
    "05.10.10"   // Logline for world relevance
  ]
}

Advanced Template Features​

Terminology Customization​

Templates can adapt language to different formats and genres:

Genre-Specific Terms

  • Horror: "Victim," "Monster," "Scare beats"
  • Comedy: "Setup," "Punchline," "Comic relief"
  • Romance: "Meet cute," "Obstacle," "Reunion"
  • Thriller: "Inciting incident," "Red herring," "Revelation"

Format Adaptations

  • Feature Film: "Three-act structure," "Plot points"
  • TV Pilot: "Teaser," "Acts," "Tag"
  • Short Film: "Setup," "Twist," "Resolution"
  • Web Series: "Episodes," "Cliffhangers," "Story arcs"

Context Relationship Mapping​

Automatic Context Loading Templates define which cards load together:

  • Character relationships: Load related character cards
  • Scene continuity: Include previous and next scenes
  • Plot consistency: Reference relevant plot points
  • Theme integration: Connect thematic elements

Smart Context Strategies

  • Hierarchical loading: Main cards first, details second
  • Relevance weighting: More important cards get priority
  • Token budgeting: Manage context size for AI efficiency
  • Dynamic adjustment: Context changes based on current work

Template System Integration​

Version Control and Templates​

Template Evolution

  • Version tracking: Changes to card and stage definitions
  • Migration tools: Update existing projects to new templates
  • Compatibility maintenance: Support for older template versions
  • User customizations: Preserve custom modifications

Project Template Management

  • Template snapshots: Freeze template state at project creation
  • Custom overlays: User modifications on top of base templates
  • Inheritance chains: Custom templates based on standard ones
  • Export capabilities: Share custom templates

Collaboration and Templates​

Team Template Strategies

  • Shared definitions: Common card and stage structures
  • Role-based templates: Different templates for different team roles
  • Style guides: Template-embedded writing guidelines
  • Quality standards: Built-in validation and suggestions

Template Libraries

  • Genre collections: Templates for specific screenplay types
  • Studio standards: Templates matching specific studio requirements
  • Personal libraries: Individual writer's custom template sets
  • Community sharing: Templates shared among BeatBandit users

Performance and Optimization​

Template Efficiency​

Loading Optimization

  • Lazy loading: Load templates only when needed
  • Caching strategies: Store frequently used templates
  • Compression: Minimize template file sizes
  • CDN distribution: Fast template delivery

AI Performance

  • Context optimization: Efficient context loading from templates
  • Instruction clarity: Clear AI guidance in templates
  • Token management: Optimal instruction length
  • Response quality: Better AI output through better templates

Debugging Template Issues​

Common Template Problems

  • Missing card definitions: Referenced cards that don't exist
  • Circular dependencies: Cards that reference each other
  • Context overflow: Too much context for AI processing
  • Inconsistent terminology: Mixed language and terms

Diagnostic Tools

  • Template validation: Check for structural issues
  • Context analysis: Understand what context loads
  • Performance monitoring: Track template loading times
  • User feedback: Identify pain points in template usage

Advanced Template Applications​

Genre-Specific Optimizations​

Horror Template Enhancements

  • Scare tracking: Cards for different types of scares
  • Tension building: Progressive fear escalation
  • Character vulnerability: Systematic character endangerment
  • Atmosphere cards: Environmental fear elements

Comedy Template Features

  • Joke structure: Setup, development, punchline tracking
  • Character quirks: Consistent comedic traits
  • Running gags: Callback and repetition management
  • Comic timing: Pacing and rhythm considerations

Professional Template Extensions​

Production Integration

  • Budget considerations: Cost-aware scene development
  • Location efficiency: Scene grouping by location
  • Casting requirements: Character breakdown integration
  • Schedule optimization: Production-friendly scene organization

Market-Focused Templates

  • Demographic targeting: Age and audience-specific content
  • Genre conventions: Market expectation compliance
  • Length requirements: Format-specific page counts
  • Commercial viability: Marketability considerations

Master the template system and you'll have unprecedented control over your screenplay development process, creating truly customized workflows that match your unique creative needs!