Creating Content

What is BDL?

The Basilisk Definition Language (BDL) is a domain-specific language used to define the structure of your data. It allows you to specify Entities, Variables, Indexes, and Data Bundles that describe how your content should be organized and accessed.

Entities

Entities are the main data structures in BDL. They define a collection of variables that represent a single concept (e.g., Character, Weapon, Quest).

entity Character {
  id: string (primary_key)
  name: string
  level: integer
  health: float
  isActive: boolean}

Entities can inherit from other entities, allowing you to create hierarchies and reuse common fields.

Variables

Variables define the properties of an entity. They support various data types and can have additional properties:

• String: Text data
• Boolean: True/false values
• Integer: Whole numbers
• Float/Double: Decimal numbers
• Enum: Predefined set of values
• Subentity: Nested entity structures
• Arrays: Collections of values

entity Weapon {
  id: string (primary_key)
  name: string
  damage: integer
  rarity: WeaponRarity (optional, default: COMMON)
  stats: WeaponStats (optional)
}

enum WeaponRarity {
  COMMON
  RARE
  EPIC
  LEGENDARY
}

subentity WeaponStats {
  critChance: float
  attackSpeed: float
}

Indexes

Indexes define how to look up entities in a dataset. They specify which variable(s) should be used as keys for efficient data retrieval.

index CharacterIndex {
  dataset: Character
  key: Character.id
}

Indexes can use single variables or combinations of variables as keys.

Data Bundles

Data Bundles group entities into deployable units. They specify which dataset to include and how to index it.

data_bundle Characters {
  dataset: Character
  index: Character.id
}

data_bundle Weapons {
  dataset: Weapon
  index: Weapon.id
}

Data Bundles can inherit from other bundles, allowing you to compose complex data structures.

Variable Properties

Variables can have various properties that control their behavior:

• primary_key: Marks a variable as the unique identifier for an entity
• optional: Allows the variable to be omitted
• default: Provides a default value if not specified
• references: Creates a reference to another entity
• unique: Ensures all values are unique across the dataset
• bundle: Groups related variables together

Comments

You can add comments in BDL files using // for single-line comments or /* */ for multi-line comments.

// This is a single-line comment
entity Character {
  id: string (primary_key) // Character's unique identifier
  name: string // Display name
  /* Multi-line comments
     can span multiple lines */
}

Creating a Definition

To create a Basilisk Definition:

1. Write your BDL file defining entities, variables, indexes, and data bundles
2. Upload the file through the Web Console or create it directly in the console
3. The system will validate your definition and generate Protocol Buffer classes
4. Once validated, you can use the definition to build data from spreadsheets

See the Configuration guide for naming conventions and best practices.

Advanced Settings

BDL supports advanced features for complex data structures:

entity BaseCharacter {
  id: string (primary_key)
  name: string
  level: integer
}

entity Hero extends BaseCharacter {
  specialAbility: string
  powerLevel: float
}

entity Weapon {
  id: string (primary_key)
  name: string
}

entity Character {
  id: string (primary_key)
  name: string
  weaponId: string (references: Weapon.id)
}

subentity Stats {
  health: float
  attack: float
  defense: float
}

entity Character {
  id: string (primary_key)
  name: string
  stats: Stats
}

databundle client {
  characters: characters
  weapons: weapons
  quests: quests
}

databundle server {
  gameConfig: gameConfig
  economy: economy
}

Retrocompatibility

Basilisk maintains backward compatibility when updating definitions. When you modify a definition:

• Existing data builds remain valid and can still be fetched
• New builds use the updated definition structure
• You can compare builds to see what changed between versions
• Protocol Buffer definitions are versioned to maintain compatibility