Data Schema Reference - Utopia Fleet Builder

This schema documents the structure of game data files used in Utopia Fleet Builder. All data is stored as JavaScript module exports containing arrays of card objects.

Overview

The Utopia data model consists of several card types, each with specific fields and structure:

Ships - Starship cards with stats and abilities
Captains - Captain cards with skill and abilities
Admirals - Admiral cards with fleet-wide effects
Ambassadors - Ambassador cards with diplomatic negotiation mechanics
Upgrades - Upgrade cards (weapons, tech, crew, elite talents)
Resources - Fleet-wide resource cards
Missions - Scenario and mission definitions
Others - Special cards and tokens

Common Fields

All card types share these base fields:

type

string

required

Card type identifier: "ship", "captain", "admiral", "ambassador", "upgrade", "resource", "mission", etc.

string

required

Unique identifier for the card (e.g., "S415", "Cap053", "A044")

gameId

number

default:1

Game identifier (always 1 for Star Trek Attack Wing)

set

array

required

Array of set identifiers this card belongs to (e.g., ["75016"], ["OP1Participation2"])

name

string

required

Display name of the card

image

string

URL to card image (typically imgur links)

unique

boolean

default:false

Whether this is a unique card (only one allowed per fleet)

factions

array

Array of faction strings: "federation", "klingon", "romulan", "dominion", "borg", "independent", etc.

cost

number

required

Squadron point cost of the card

text

string

Card ability text with HTML formatting and special image tags for icons

Ship Cards

Required Fields
Optional Fields
Example

type

string

required

Always "ship"

class

string

required

Ship class name (e.g., "Sovereign Class", "Galaxy Class")

attack

number

required

Primary weapon attack dice

agility

number

required

Base agility (defense dice)

hull

number

required

Hull points

shields

number

required

Shield points

actions

array

required

Array of action types available:

"evade"
"target-lock"
"scan"
"battlestations"
"cloak"
"sensor-echo"
"regenerate"

upgrades

array

required

Array of upgrade slot types:

"tech"
"weapon"
"crew"
"talent"
"borg"
"squadron"

alliance

boolean

default:false

Whether this ship has alliance special rules

squadron

boolean

default:false

Whether this is a squadron/fighter ship

intercept

object

Intercept rules object with ship and fleet properties (typically empty objects {})

{
  "type": "ship",
  "id": "S415",
  "gameId": 1,
  "set": ["75016"],
  "name": "U.S.S. Atlas",
  "image": "https://i.imgur.com/w2HBtk3.png",
  "class": "Sovereign Class",
  "actions": ["evade", "target-lock", "scan", "battlestations"],
  "upgrades": ["tech", "weapon", "weapon", "crew", "crew"],
  "attack": 5,
  "agility": 1,
  "hull": 5,
  "shields": 5,
  "cost": 29,
  "text": "<b>WHENEVER THIS SHIP PERFORMS A</b> [battlestations]...",
  "unique": true,
  "alliance": false,
  "factions": ["federation"],
  "intercept": {
    "ship": {},
    "fleet": {}
  },
  "squadron": false
}

Captain Cards

Required Fields
Optional Fields
Example

type

string

required

Always "captain"

skill

number

required

Captain skill number (typically 1-10)

talents

number

default:0

Number of Elite Talent slots this captain provides (0, 1, or 2)

range

string

Range for captain abilities (e.g., "1", "1 - 2", "1 - 3")

hullConstraint

string

Hull requirement for this captain (e.g., "5+", "4+")

{
  "type": "captain",
  "id": "Cap049",
  "gameId": 1,
  "set": ["75016"],
  "name": "Jean-Luc Picard",
  "image": "https://i.imgur.com/jDXSyy0.jpg",
  "unique": true,
  "text": "<b>EACH TIME AN OPPOSING EFFECT WOULD DISCARD...</b>",
  "factions": ["federation"],
  "cost": 6,
  "skill": 9,
  "talents": 1
}

Admiral Cards

Required Fields
Optional Fields
Example

type

string

required

Always "admiral"

skill

number

required

Skill bonus when admiral replaces captain (typically 0-3)

{
  "type": "admiral",
  "id": "A044",
  "gameId": 1,
  "set": ["75016"],
  "name": "James T. Kirk",
  "image": "https://i.imgur.com/8UfzzIf.png",
  "unique": true,
  "text": "Add 2 [crew_text] to this ship's Upgrade Bar...",
  "factions": ["federation"],
  "cost": 5,
  "skill": 0,
  "talents": 1,
  "range": "1 - 2"
}

Ambassador Cards

Ambassadors are diplomatic cards that offer negotiation mechanics with two possible outcomes.

Required Fields
Optional Fields
Example

type

string

required

Always "ambassador"

cost

number

required

Squadron point cost (typically 3-5 SP)

text

string

required

Contains two sections:

NEGOTIATIONS ACCEPTED: Benefits for both players
NEGOTIATIONS DENIED: Consequences or penalties

{
  "type": "ambassador",
  "id": "M013",
  "gameId": 1,
  "set": ["75014"],
  "name": "Neelix",
  "image": "https://i.imgur.com/cJ30nme.png",
  "cost": 3,
  "text": "NEGOTIATIONS ACCEPTED: For the rest of the game, if this ship moves within Range 1 of the target ship or the target ship moves within Range 1 of this ship. Place either a [battlestations] or [evade] Token beside the ship that moved. NEGOTIATIONS DENIED: This ship gains the following ability: END PHASE: Select either a [battlestations], [evade], or [scan] Token beside this ship. That token does not get removed this End Phase.",
  "unique": true,
  "factions": ["federation", "independent"]
}

Upgrade Cards

Upgrade cards have different subtypes: tech, weapon, crew, talent, borg, squadron, question

Tech Upgrades
Weapon Upgrades
Crew Upgrades
Elite Talents

type

string

required

"tech" for technology upgrades

alliance

boolean

default:false

Alliance restriction

{
  "type": "tech",
  "id": "T312",
  "set": ["75016"],
  "name": "Advanced Shields",
  "image": "https://i.imgur.com/example.png",
  "cost": 3,
  "text": "<b>ACTION:</b> Disable this card...",
  "unique": true,
  "alliance": false,
  "factions": ["federation"]
}

type

string

required

"weapon" for weapon upgrades

attack

number

Attack dice for weapon

range

string

Attack range (e.g., "1-2", "2-3")

{
  "type": "weapon",
  "id": "W123",
  "name": "Photon Torpedoes",
  "cost": 5,
  "attack": 5,
  "range": "2-3",
  "text": "<b>ATTACK (TARGET LOCK):</b> Spend your Target Lock...",
  "factions": ["federation"]
}

type

string

required

"crew" for crew upgrades

{
  "type": "crew",
  "id": "C456",
  "name": "Montgomery Scott",
  "cost": 3,
  "unique": true,
  "text": "<b>ACTION:</b> Disable 2 of your Shields...",
  "factions": ["federation"]
}

type

string

required

"talent" for elite talent upgrades

{
  "type": "talent",
  "id": "ET789",
  "name": "Push the Limits",
  "cost": 4,
  "text": "<b>ACTION:</b> Perform 1 additional Action...",
  "factions": ["federation"]
}

Special Upgrade Fields

Upgrades may have additional constraint fields:

OnePerShip

boolean

Only one copy allowed per ship

shipFederation

boolean

Requires Federation ship

costFederation

string

Additional cost for Federation ships (e.g., "+1")

sovereignLimit

boolean

Limited to Sovereign class ships

hullConstraint

string

Hull requirement (e.g., "4+", "5+")

Resource Cards

Structure
Example

type

string

required

Always "resource"

opBanned

boolean

default:false

Whether this resource is banned in organized play

showShipResourceSlot

boolean

default:false

Display option for resource slot

{
  "type": "resource",
  "id": "R001",
  "gameId": 1,
  "set": ["OP1Participation2"],
  "name": "Elite Attack Die",
  "text": "1) Once during every round, a player may...",
  "cost": 5,
  "opBanned": true,
  "showShipResourceSlot": false
}

Mission Cards

Structure
Example

type

string

required

Always "mission"

missionSet

array

required

Array of mission set identifiers

missionID

string

required

Unique mission identifier

Componets

string

Components required (note: typo in source - “Componets”)

description

string

Mission narrative and background

setUp

string

Setup instructions including point limits and requirements

specialRules

string

Special rules for the mission

objectives

string

Victory conditions and objectives

{
  "type": "mission",
  "name": "A New Source Of Dilithium",
  "missionSet": ["a_new_source_of_dilithium"],
  "missionID": "a_new_source_of_dilithium",
  "Componets": "1 Planet Token and 12 Mission Tokens",
  "description": "Rumors of a new planet harboring dilithium...",
  "setUp": "FEDERATION PLAYER\n40 Squadron Points...",
  "specialRules": "Ships moving through, overlapping...",
  "objectives": "Any player who possesses at least 3 Mission Tokens..."
}

Other Card Types

Token Cards

Special game tokens and rules references:

{
  "type": "token",
  "id": "rule_starshipconstruction",
  "gameId": 1,
  "set": ["AdditionalRules"],
  "name": "Starship Construction",
  "text": "Starship Construction Cards are cards featuring..."
}

Question Cards

Special utility cards for fleet building:

{
  "type": "question",
  "id": "Q036",
  "gameId": 1,
  "set": ["75016"],
  "name": "Systems Upgrade",
  "cost": 2,
  "text": "This card may fill a [weapon_text] or [tech_text] Slot.",
  "OnePerShip": true,
  "shipFederation": true,
  "factions": ["federation"]
}

Text Formatting

Card text uses HTML and special image tags:

<b>ACTION:</b> - Action ability
<b>WHEN ATTACKING:</b> - Attack timing
<b>WHEN DEFENDING:</b> - Defense timing  
<b>END PHASE:</b> - End phase timing
<b>PLANNING PHASE:</b> - Planning phase timing

Data File Structure

All data files follow this pattern:

module.exports = [
  {
    // Card object 1
    type: "ship",
    id: "S001",
    // ... other fields
  },
  {
    // Card object 2  
    type: "ship",
    id: "S002",
    // ... other fields
  }
  // ... more cards
];

Available Data Files

ships.js

All ship cards with stats and abilities

captains.js

Captain cards with skills and talents

admirals.js

Admiral cards with fleet abilities

ambassadors.js

Ambassador cards with negotiation mechanics

upgrades.js

All upgrade cards (tech, weapon, crew, talents)

resources.js

Fleet resource cards

missions.js

Mission scenarios and objectives

others.js

Special tokens and rules cards

sets.js

Set and expansion definitions

ship_classes.js

Ship class definitions and groupings

missionSets.js

Mission set collections

starship_construction.js

Starship construction rules and cards

rulings.js

Official game rulings and clarifications

Validation Rules

When working with this data:

Required Fields - All cards must have type, id, name, and cost

Unique IDs - Card IDs must be unique across all cards of same type

Valid Types - Type must be one of the documented card types

Faction Arrays - Factions must be arrays, even for single faction

Numeric Fields - Stats (attack, agility, etc.) must be numbers

Some legacy data may have inconsistencies (e.g., “Componets” typo in missions). Preserve these for compatibility.

Usage Examples

const ships = require('./data/ships.js');
const federationShips = ships.filter(ship => 
  ship.factions && ship.factions.includes('federation')
);

FAQ

Frequently asked questions

Rulings

Official game rulings and clarifications

Resources

​Overview

​Common Fields

​Ship Cards

​Captain Cards

​Admiral Cards

​Ambassador Cards

​Upgrade Cards

​Special Upgrade Fields

​Resource Cards

​Mission Cards

​Other Card Types

​Text Formatting

​Data File Structure

​Available Data Files

ships.js

captains.js

admirals.js

ambassadors.js

upgrades.js

resources.js

missions.js

others.js

sets.js

ship_classes.js

missionSets.js

starship_construction.js

rulings.js

​Validation Rules

​Usage Examples

​Related Documentation

FAQ

Rulings

Build docs developers (and LLMs) love

Overview

Common Fields

Ship Cards

Captain Cards

Admiral Cards

Ambassador Cards

Upgrade Cards

Special Upgrade Fields

Resource Cards

Mission Cards

Other Card Types

Text Formatting

Data File Structure

Available Data Files

Validation Rules

Usage Examples

Related Documentation