Managing Entities

Entities are the core data objects in StudioBrain. Each entity represents something in your world — a character, location, faction, item, quest, or any other type defined by a template. This guide covers the template system, creating and editing entities, validation with rules, and organizing your project.

Entity Types

StudioBrain ships with 15 built-in entity type templates. Each type is defined by a template file in _Templates/Standard/, and you can add your own.

How Entity Types Work — The Template System

Templates are the foundation of StudioBrain. They define the structure of every entity type, and the entire system — from the editor UI to the AI generation to the TypeScript type safety — builds on top of them.

What Templates Do

A template is a Markdown file with YAML frontmatter that lists every field an entity of that type can have. When StudioBrain reads your project:

1. Templates define fields — Every field you see in the Visual Editor comes from a template. Text fields, arrays, entity references, nested objects, production status — all declared in the template.
2. Types auto-generate — The backend reads templates and generates TypeScript interfaces and Zod validation schemas automatically. This means the frontend has compile-time type safety for every entity field.
3. UI renders dynamically — The Visual Editor renders form fields based on the template definition. No UI code changes are needed to support new fields or entity types.
4. AI understands structure — Templates are included as context when the AI generates content, so it knows exactly what fields to produce and what format to use.

Template File Format

Every template follows the same structure: YAML frontmatter containing field definitions, followed by a Markdown body describing the entity type.

Here is a simplified excerpt from the Character template:

---
# METADATA
template_version: "2.0"
id: "[snake_case_name]"
entity_type: "character"
created_date: "[YYYY-MM-DD]"
last_updated: "[YYYY-MM-DD]"
status: "active"
 
# PRODUCTION STATUS TRACKING
production_status:
  general: "concept"
  game_uefn: "none"
  tv_showrunner: "none"
  notes: ""
 
# PRIMARY IMAGE
primary_image: ""
 
# BASIC IDENTITY
name: "[Generate Full Name]"
nickname: "[Generate Nickname]"
age: "18"
gender: "[male/female/non-binary]"
species: "human"
 
# TEMPORAL INFORMATION
birth_year: null
death_year: null
key_dates: []
current_age_reference_year: 1998
 
# PHYSICAL DESCRIPTION
height: "[Height in feet/inches]"
build: "[slim/average/muscular/heavyset]"
hair_color:
  name: ""
  hex: ""
eye_color:
  name: ""
  hex: ""
distinguishing_features:
  - "[Unique physical feature 1]"
 
# RELATIONSHIPS
faction: "[Faction affiliation or independent]"
family: []
friends: []
enemies: []
romantic: []
 
# PERSONALITY & PSYCHOLOGY
personality_traits:
  - "[Core trait 1]"
  - "[Core trait 2]"
fears: []
motivations: []
secrets: []
 
# SKILLS & ABILITIES
primary_skills: []
secondary_skills: []
special_abilities: []
 
# AI GENERATION HELPERS
ai_profile_description: ""
ai_voice_style: ""
ai_bio_summary: ""
dialogue_samples: []
---
 
# [Character Full Name]
 
## Background
[Narrative content goes here...]
 
## Personality
[Free-form description...]
 
## Defining Moment
[Pivotal event that shaped the character...]

Key things to notice:

• Every field is declared — the template acts as the schema. The placeholder values (like "[Generate Full Name]") serve as hints for both human creators and AI generators.
• Nested objects are supported — fields like hair_color with name and hex sub-fields, or production_status with multiple tracking fields.
• Arrays are supported — personality_traits, friends, dialogue_samples, etc.
• Entity references — Fields like faction and primary_location reference other entities by ID.
• Markdown body — Below the YAML frontmatter, free-form narrative content provides rich descriptions that go beyond structured fields.

Field Types in Templates

Templates support the following field types, determined by the YAML value format:

Adding a New Entity Type

One of StudioBrain’s most powerful features is that adding a new entity type requires zero code changes. To create a custom entity type:

1. Create a template file in _Templates/Standard/:

   _Templates/Standard/VEHICLE_TEMPLATE.md

2. Define the fields in YAML frontmatter:

   ---
   template_version: "1.0"
   id: "[snake_case_name]"
   entity_type: "vehicle"
   created_date: "[YYYY-MM-DD]"
   last_updated: "[YYYY-MM-DD]"
   status: "active"
    
   production_status:
     general: "concept"
    
   primary_image: ""
    
   name: "[Vehicle Name]"
   vehicle_type: "[car/truck/motorcycle/aircraft/boat]"
   manufacturer: "[Brand reference]"
   year: 0
   top_speed: ""
   fuel_type: ""
   condition: "[pristine/good/worn/damaged/wrecked]"
   owner: "[Character reference]"
   location: "[Location reference]"
   special_modifications: []
   ---
    
   # [Vehicle Name]
    
   ## Description
   [Physical description and history of this vehicle...]

3. Regenerate types — Run the type generator (this happens automatically on npm run dev):

   npm run generate:types

4. Start using it — The new “Vehicle” entity type appears in the sidebar, the Visual Editor renders all your fields, the AI Workshop understands the schema, and TypeScript types are available for any custom UI components.

Production Status Tracking

Every template includes a production_status block that tracks an entity’s progress across multiple pipelines:

The Production Status component block in the Visual Editor provides a visual pipeline tracker for these fields.

Validation and Rules

Rules files in the _Rules/ directory define constraints for AI generation and power the Validation Panel in the entity editor. There are 16 rules files covering entity-specific and cross-cutting concerns.

How Rules Work

Each rules file is a Markdown file with YAML frontmatter containing:

• system_prompt — Context provided to the AI when generating content for this entity type. This shapes the AI’s understanding of tone, setting, and constraints.
• rules — A list of individual validation rules, each with an ID, category, priority, and validation type.

Here is a simplified excerpt from CHARACTER_RULES.md:

---
system_prompt: "Generate a character for the universe. Characters should
  reflect the era's culture while showing impact of corporate environmental
  neglect. Balance humor with genuine trauma."
entity_type: character
template_reference: CHARACTER_TEMPLATE.md
 
rules:
- id: char_001
  category: identity
  priority: critical
  rule: Every character MUST have a primary_location
  validation_type: error
 
- id: char_002
  category: naming
  priority: critical
  rule: Character IDs must use lowercase_with_underscores format
  validation_type: error
 
- id: char_003
  category: relationships
  priority: high
  rule: Friends always use nicknames when available
  validation_type: warning
 
- id: char_004
  category: timeline
  priority: critical
  rule: No modern technology references
  validation_type: error
 
- id: char_005
  category: tone
  priority: high
  rule: Characters must balance dark humor with genuine trauma
  validation_type: warning
---

Rule Priorities

Validation Types

The Validation Panel

The Validation Panel appears in the entity editor and checks your entity data against the rules defined for its type. It shows:

• Errors (red) — Critical issues such as missing required fields, invalid ID formats, or rule violations
• Warnings (yellow) — Non-critical issues such as suggested fields that are empty or style inconsistencies
• Info (blue) — Informational notes and suggestions

When all fields pass validation, the panel shows a green “All fields valid” indicator.

Each validation issue includes:

• The field path that has the problem
• A description of what needs to change
• A clickable link to navigate directly to the field in the editor

Available Rules Files

The Fix Dialog

Clicking the Fix button (wrench icon) on a validation issue opens the Fix Dialog, which offers three tiers of automated repair:

The Fix Dialog presents a diff view (side-by-side comparison) so you can review exactly what changes will be made before applying them.

Creating a New Entity

1. Navigate to the entity type list page (e.g., Characters in the sidebar).
2. Click the New button in the top-right corner.
3. Fill in the required fields — at minimum, the entity needs a name.
4. Click Save to create the entity file.

The entity is stored as a Markdown file in the project directory. For example, a character named “Rex Marshall” creates:

Characters/rex_marshall/CH_rex_marshall.md

The file follows the structure defined by the entity’s template, with your field values filled in and the Markdown body section ready for narrative content.

Entity Data Structure

Every entity is backed by a Markdown file with two parts, defined by its template:

Frontmatter Fields

Structured data stored as YAML key-value pairs. These are the fields you see in the Visual Editor. The available fields come from the entity’s template:

---
name: Rex Marshall
nickname: Rex
age: "34"
gender: male
species: human
faction: the_syndicate
primary_location: downtown_district
personality_traits:
  - resourceful
  - cynical
  - loyal
production_status:
  general: wip
  game_uefn: concept
  tv_showrunner: draft
relationships:
  - entity: sara_chen
    type: ally
    description: Trusted partner from the old days
---

Markdown Body

Free-form narrative content that follows the frontmatter, separated by ---:

---
name: Rex Marshall
...
---
 
# Rex Marshall
 
## Background
 
Rex Marshall grew up in the corporate districts before a
scandal forced him underground. Now he works as muscle
for The Syndicate, though his loyalties are more complex
than they appear.
 
## Defining Moment
 
The night of the Blackout Incident changed everything...

The Markdown body sections are also defined by the template — each template includes section headings (Background, Personality, Defining Moment, etc.) that guide content creation.

Editing Entities

Visual Editor Tab

The Visual Editor presents your entity’s fields in an organized, form-based layout. Sections are defined by layout JSON files and the entity’s template. Field types include:

• Text fields — Single-line inputs for names, titles, IDs
• Textarea fields — Multi-line inputs for descriptions and notes
• Select/Dropdown fields — Choosing from predefined options (e.g., status, type, condition)
• Array fields — Lists of strings (e.g., skills, equipment, traits)
• Complex array fields — Lists of objects (e.g., relationships with entity reference, type, and description)
• Entity reference fields — Link to other entities with inline search and auto-complete
• Number fields — Numeric values for ages, counts, scores
• Nested object fields — Grouped sub-fields (e.g., hair_color with name and hex)
• Rating selectors — Numeric scales for attributes like threat level or influence

YAML Editor Tab

For power users, the YAML tab gives you direct access to the raw frontmatter in a full Monaco code editor with syntax highlighting, auto-completion, and error detection. Changes validate in real-time.

Markdown Editor Tab

The Markdown tab provides a rich editor for the entity’s narrative body content. You can write and preview Markdown with support for headings, lists, tables, code blocks, links, and images.

Component Blocks

Layout sections can contain component blocks — rich interactive widgets that go beyond simple form fields:

Plugin blocks can also be placed in layouts, extending the editor with custom functionality.

Organizing Entities

Search and Filtering

Each entity list page includes:

• Text search — Filter entities by name or content
• Category filters — Filter by type-specific categories (e.g., faction type, item rarity, production status)
• Sort options — Sort by name, date created, date modified, or other fields

Cross-Entity Search

The Cross-Entity Search page (accessible from the sidebar) lets you search across all entity types at once. This is useful for finding references to a character across locations, factions, items, and quests.

Relationship Graph

The Relationship Graph provides a visual network view of all entity connections. Nodes represent entities and edges represent relationships. You can:

• Pan and zoom the graph
• Click nodes to navigate to entities
• Filter by entity type or relationship type
• See relationship strength and direction

Recycle Bin

Deleted entities are moved to the Recycle Bin rather than permanently destroyed. From the Recycle Bin you can restore entities or permanently delete them.

Entity File Naming Conventions

StudioBrain uses consistent file naming conventions for each entity type:

Entity IDs always use lowercase_with_underscores format.

Next Steps

• AI Workshop — Generate and refine content using AI with template and rules context
• Sync & Collaboration — Sync entities across desktop and cloud
• Settings & Configuration — Template management and plugin configuration
• Using Plugins — Extend the entity editor with plugin panels