Managing Entities

Entities are the core data objects in City of Brains Studio. Each entity represents something in your world — a character, location, faction, item, district, brand, or job role. This guide covers creating, editing, validating, and organizing entities.

Entity Types

Entity types are provided by activated templates. When you install and activate a template, its entity types become available in your project. If no templates are installed, you’ll see a message prompting you to install one.

Built-in Entity Types

The following entity types are included in the standard template:

Creating a New Entity

1. Navigate to the entity type list page (e.g., Characters in the sidebar)
2. Click the New button (typically 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 YAML file in the project directory, e.g., Characters/rex_marshall.yaml.

Entity Data Structure

Every entity is backed by a YAML file with two parts:

Frontmatter Fields

Structured data stored as YAML key-value pairs. These are the fields you see in the Visual Editor:

name: Rex Marshall
role: Enforcer
faction: The Syndicate
status: active
description: A former corporate security specialist turned underground enforcer.
relationships:
  - entity: sara_chen
    type: ally
    description: Trusted partner from the old days
production_status:
  general: wip
  game: concept
  tv: draft

Markdown Body

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

---
name: Rex Marshall
role: Enforcer
...
---
 
# 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.
 
## Key Events
 
- **2045**: Recruited by Nexus Corp security division
- **2048**: The Blackout Incident — forced into hiding
- **2050**: Joins The Syndicate as an enforcer

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 may include:

• Text fields — Simple single-line inputs for names, titles, etc.
• Textarea fields — Multi-line inputs for descriptions and notes
• Select/Dropdown fields — Choosing from predefined options (e.g., faction type, status)
• Array fields — Lists of values (e.g., skills, equipment, allies)
• Complex array fields — Lists of objects (e.g., relationships with entity reference + type + description)
• Entity reference fields — Link to other entities with inline search and selection
• 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.

Markdown Editor Tab

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

Component Blocks

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

• Entity Assets — Upload and manage images, set primary image, assign asset roles
• Entity Timeline — View and manage chronological events for the entity
• Entity Chat — AI-powered conversational editing panel
• Entity Relationships — Auto-discovered relationship links rendered as grouped cards
• Production Status — Pipeline status editor (general/game/TV status)
• Primary Image — Hero image display with placeholder fallback
• Markdown Content — Rendered markdown body preview

Validation

Validation Panel

The Validation Panel appears in the entity editor and checks your entity data against the rules defined in the entity’s template. It shows:

• Errors (red) — Critical issues that should be fixed (e.g., missing required fields)
• Warnings (yellow) — Non-critical issues (e.g., suggested fields that are empty)

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 is wrong
• A clickable link to navigate directly to the offending field

Fix Dialog

Clicking the Fix button (wrench icon) 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.

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)
• 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, and items.

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.

Tier Limits

StudioBrain enforces subscription-tier limits on entity creation to manage resource usage across tenants.

Free Tier

• Entity cap: 10 entities by default (configurable by administrators via FREE_TIER_ENTITY_LIMIT)
• When approaching the limit (≥ 80% used), a warning banner appears showing remaining slots
• At the limit, entity creation is blocked with a message prompting upgrade

Paid Tiers (Indie, Team, Enterprise)

• No entity creation limits — unlimited entities
• Storage configuration may still be required depending on deployment settings

Storage Configuration Gate

In some deployments, entity creation requires a storage provider to be configured first. This ensures entities have a persistent backend for their markdown and asset files. If this gate is enabled and storage is not configured, you’ll see an error when attempting to create an entity.

Checking Your Usage

Navigate to Settings → Entity Types or the New Entity page to see your current usage: entity count, tier limit, and storage status. The frontend shows a real-time banner:

• Green: You can create entities
• Yellow warning: Approaching your limit (≥ 80% used)
• Red error: Blocked — either storage not configured or tier limit reached

Next Steps

• AI Workshop — Generate and refine content using AI
• Component Blocks Reference — Technical details of all available component blocks
• Layout System Architecture — How layouts and sections are structured