Extending the System

This manual covers how to add new content to the Star Trek Adventures system — new species, new equipment, new starship classes, or entirely new file types.

Adding New Species

To add a new species (e.g., Romulan, Cardassian, Bajoran):

1. Create a new Species file in the /Species/ folder.
2. Set attribute and discipline bonuses — keep them balanced (total bonuses should be roughly +2 to +4 across all attributes and disciplines combined).
3. Add special abilities — 1-2 unique traits or talents that reflect the species' distinctive biology or culture.
4. Write the description — 2-3 sentences about what makes this species interesting for roleplay.

Balance Guidelines:

• Attribute bonuses: +0 to +2 per attribute, total of +2 to +4 across all six.
• Discipline bonuses: +0 to +1 per discipline, total of +1 to +2 across all six.
• Special abilities: 1-2 abilities, each with a clear mechanical effect.
• No species should be strictly better than another — they should be different.

Adding New Equipment

To add a new piece of equipment:

1. Create a new Equipment file in the /Equipment/ folder.
2. Set the category (weapon, armor, gear, device, etc.).
3. Fill in the relevant stats — damage for weapons, shield rating for armor, power for devices.
4. Write the description and any special rules in the notes field.

Equipment Categories:

• Weapon — Fill in damage, damageType, range.
• Armor — Fill in shieldRating, encumbrance.
• Gear — General equipment, tools, personal items.
• Device — Powered devices that consume power.
• Consumable — Single-use items.

Adding New Starships

To add a new starship class:

1. Create a new Starship file in the /Starships/ folder.
2. Set systems (Communications, Computers, Engines, Sensors, Weapons) — scale 1-10.
3. Set departments (Command, Conn, Engineering, Science, Security) — scale 1-5.
4. Set shields, hull, and power maximums.
5. Add ship talents — special abilities of the vessel.
6. Choose a mission profile — affects department bonuses.

Balance Guidelines:

• A small escort (Defiant-class): systems 6-8, departments 3-4, shields 8, hull 10.
• A cruiser (Galaxy-class): systems 7-9, departments 4-5, shields 12, hull 14.
• A science vessel (Olympic-class): systems 8-10 (especially Sensors), departments 3-4, shields 6, hull 8.

Adding New File Types

If you need a type of content that doesn't fit existing file types:

1. Read the platform instructions for creating file types.
2. Design the schema — define fields, types, constraints, and relationships.
3. Create the file type with the write tool at /file-types/<slug>.json.
4. Add reference fields to existing types that should link to the new type.
5. Create sample content to populate the new type.

Example: Adding an Organisation type

• Schema: name, faction, goals, territory, members (references to characters), resources, notes.
• Add a faction reference field to Character and Mission types.
• Create sample organisations: Starfleet Command, Klingon Defence Force, Romulan Tal Shiar.

Customising Layouts

Every file type can have a layout — a JSON spec that controls how files render. Layouts use a component system with elements like:

• ImageHeader — Hero image with title overlay.
• StatGrid — Grid of label/value pairs.
• DataTable — Structured rows for lists and records.
• BadgeList — Wrapped row of tags and labels.
• FileReferenceGrid — Cards for arrays of referenced files.
• Progress — Progress bars for stress, shields, hull.
• Markdown — Rendered markdown for long-form text.

Read the platform instructions for designing layouts when you want to customise how a file type looks.

Modifying the Player's Handbook

The Player's Handbook is a chaptered book. To add or modify chapters:

1. Read /project.json to see the current chapter list.
2. Write a new chapter at /handbooks/player/<chapter-id>.md with YAML frontmatter.
3. Update the chapter index via update /project.json on settings.playerHandbook.chapters.

Chapter Guidelines:

• 400-1,500 words per chapter.
• One job per chapter, titled as the reader would ask for it.
• Use ## for sections, ### sparingly.
• Tables and lists for reference material. Prose for rules that need to be absorbed.
• Link to real files using <@referenceId> mentions.