Templates

Templates are the foundation of StudioBrain’s type system. Every entity, document, and map is created from a template that defines its fields, structure, and behavior. Templates are markdown files with YAML frontmatter — no code changes required to create new types.

Three Template Categories

StudioBrain templates fall into three categories, each with a different editing experience.

Entity Templates

Entity templates define structured data types: characters, locations, items, creatures, plants, recipes, or any other object your project needs.

Aspect	Details
Category	`entity`
Editor	Field-by-field form based on frontmatter fields
Storage	Markdown file with YAML frontmatter
Examples	CHARACTER_TEMPLATE.md, LOCATION_TEMPLATE.md, PLANT_TEMPLATE.md

Entity templates are the most common type. Each field in the YAML frontmatter becomes an editable field in the UI.

Document Templates

Document templates define structured long-form content: game design documents, story bibles, style guides, lore compendiums.

Aspect	Details
Category	`document`
Editor	Rich text editor (TipTap) with section outline
Storage	Markdown file with YAML frontmatter + rich text body
Examples	GDD_TEMPLATE.md, STORY_BIBLE_TEMPLATE.md, STYLE_GUIDE_TEMPLATE.md

Document templates use the markdown body as the primary content area. The frontmatter holds metadata (author, status, version) shown in the sidebar.

Map Templates

Map templates define spatial visualizations: world maps, floor plans, pinboards, garden layouts.

Aspect	Details
Category	`map`
Editor	Map canvas with pins, lines, layers, and pan/zoom
Storage	Markdown file with YAML frontmatter (pins/layers in frontmatter)
Examples	WORLD_MAP_TEMPLATE.md, FLOOR_PLAN_TEMPLATE.md

Map templates define pin types, default layers, and the rendering engine used by the map editor.

Creating Custom Templates

Step 1: Choose a Category

Decide whether your new type is an entity, document, or map based on its primary editing experience:

Users fill in structured fields —> Entity
Users write long-form text with sections —> Document
Users place items on a visual canvas —> Map

Step 2: Create the Template File

Templates live in _Templates/Standard/ (entities and documents) or _Templates/Maps/ (maps).

Entity template (_Templates/Standard/RECIPE_TEMPLATE.md):

---
template_version: "2.0"
id: "[snake_case_name]"
entity_type: "recipe"
template_category: "entity"
name: "[Recipe Name]"
description: "[Brief description]"
 
cuisine: "[Italian/Mexican/Japanese/etc.]"
difficulty: "medium"
prep_time_minutes: 30
cook_time_minutes: 45
servings: 4
 
ingredients:
  - name: "[Ingredient]"
    amount: "[Amount]"
    unit: "[cups/tbsp/oz]"
 
steps:
  - "[Step 1 instructions]"
  - "[Step 2 instructions]"
 
tags: []
primary_image: ""
---
 
# [Recipe Name]
 
## Description
 
[Describe the dish, its origin, and what makes it special.]
 
## Chef's Notes
 
[Tips, variations, and serving suggestions.]

Document template (_Templates/Standard/BRAND_GUIDE_TEMPLATE.md):

---
template_version: "2.0"
id: "brand_guide"
entity_type: "brand_guide"
template_category: "document"
name: "Brand Guide"
description: "Brand identity and usage guidelines"
icon: "Palette"
capabilities:
  - outline_view
  - export_pdf
  - rich_text
status: "draft"
---
 
# Brand Guide
 
## Brand Identity
[Describe the brand's core identity.]
 
## Logo Usage
[Logo files, clear space rules, acceptable backgrounds.]
 
## Color Palette
[Primary and secondary colors with hex codes.]

Map template (_Templates/Maps/GARDEN_MAP_TEMPLATE.md):

---
template_version: "2.0"
id: "garden_map"
entity_type: "map"
template_category: "map"
name: "Garden Map"
renderer: "canvas2d"
coordinate_system: "pixel"
 
pin_types:
  - id: "plant_bed"
    label: "Plant Bed"
    icon: "Sprout"
    color: "#22c55e"
    entity_types: ["plant"]
 
default_layers:
  - id: "beds"
    name: "Plant Beds"
    color: "#22c55e"
 
export_formats: ["png", "json"]
---
 
# Garden Map
[Plan your garden layout.]

Templates can specify which UI widget renders each field using the field_config section. For example, a character template can define specific color palettes for hair and eye color, or constrain a year field to a valid range.

For details on field_config syntax, see Template Authoring — field_config.

Step 3: Use the Template

After saving the template file, it appears in the + New dialog under the appropriate category tab. Create a new instance by selecting the template and entering a name.

Template Frontmatter Reference

Required Fields (All Categories)

Field	Type	Description
`template_version`	string	Schema version, must be `"2.0"`
`id`	string	Unique identifier (snake_case)
`entity_type`	string	Type name (lowercase, used in URLs and API)
`template_category`	string	`"entity"`, `"document"`, or `"map"`
`name`	string	Display name

Optional Fields (All Categories)

Field	Type	Description
`description`	string	Brief description shown in template picker
`icon`	string	Lucide icon name
`primary_image`	string	Default image field
`status`	string	Default status value
`tags`	array	Default tags

Document-Specific Fields

Field	Type	Description
`capabilities`	array	Enabled features: `outline_view`, `export_pdf`, `rich_text`

Map-Specific Fields

Field	Type	Description
`renderer`	string	Renderer ID: `canvas2d`, `svg`, or a plugin renderer
`coordinate_system`	string	`pixel` (image-based) or `geo` (lat/lng)
`pin_types`	array	Available pin types with icons and linked entity types
`default_layers`	array	Layers created when a new map is made from this template
`export_formats`	array	Available export formats: `png`, `svg`, `json`

Field Types

Entity template frontmatter fields are automatically rendered as form inputs based on their YAML type:

YAML Type	Rendered As
`string` (quoted)	Text input
`number` (integer)	Number input
`boolean` (`true`/`false`)	Toggle switch
`array` (list `- items`)	Multi-value input (add/remove items)
`object` (nested keys)	Grouped fields
`null`	Optional field (empty by default)
Color object `{ name, hex }`	Color picker

Template Marketplace

Share your templates with the community through the StudioBrain Template Marketplace.

Publishing Requirements

Requirement	Details
`template_version`	Must be `"2.0"` or higher
`description`	Non-empty description
Fields	At least 5 fields defined
No private references	No references to project-specific entity types
Valid category	Must be `entity`, `document`, or `map`

How to Publish

Go to Settings > Templates
Select a template and click Publish to Marketplace
Add a screenshot and detailed description
Submit for review

Published templates appear in the Marketplace for other users to install.

Installing from Marketplace

Go to Settings > Templates > Marketplace
Browse or search for templates
Click Install to add a template to your project
New instances can be created from the installed template immediately