Modules

A module is a .zip archive that defines the structure of a character sheet and how the values of the automated fields are derived. It must contain the following files:

├── meta.json
├── sheet_definition.lua
└── static_data.lua

Meta

Contains the basic information of the module.

{
  "name": "Guide to Everything",
  "system": "D&D 5E",
  "version": "0.2",
  "author": "Xanathar"
}

Sheet Definition

Contains the structure and mechanics of the character sheet. The script must return a CharacterSheet object.

Static Data

Static data is a secondary lua script that returns a table that can be referenced in the lambdas calculating the values of fields in the character sheet. This is useful for separating the mechanics and structure of the character sheet (sheet_definition.lua) and larger chunks of static values and text (e.g. descriptions, common values etc.).

The contents of static_data.lua and sheet_definition.lua are combined into a single final lua script before evaluation.

Tyche Lua Library

The library of custom methods can be accessed using the global tyche table in Lua.

Override

Sets the override value of a character sheet component. This is the same as manually overriding the value from the UI but from Lua.

function override(id, property, value) end

Parameters

Example

tyche.override("str", "value", 10)

Clear Override

Clears the override value of a character sheet component.

function clearoverride(id, property) end

Parameters

Example

tyche.clearoverride("str", "value")

Character Sheet Components

Character sheets are built from a tree of components. Each component has a number of mandatory and optional fields and certain container components can have a list of embedded components. Every component (with the exception of the top-level CharacterSheet) must have a unique id that is used to reference it from other components.

Values of Properties

The values of component properties must be one of the following types:

• string
• number (double)
• boolean

Dynamic Property Values

Instead of directly specifying the value of a property, a lambda function can also be specified to dynamically calculate the final value. Every property (with the exception of id) can also be set by a lambda function. These must have the following signature:

function(sheet) return value end

The parameter is a table containing all other components of the character sheet, indexed by their id. For example to define a strength ability score modifier derived from the strength value:

AbilityScore {
  id = "str",
  name = "Strength",
  value = 9,
  modifier = function(sheet) return math.floor((sheet["str"].value - 10) / 2) end,
}

Character Sheet

CharacterSheet {
  Stat {}
  AbilityScore {}
  ...
}

Variable

Variable {
  id: string;                   -- required
  value: number | function;     -- optional (default: 0)
}

Stat

Stat {
  id: string;                   -- required
  name: string | function;      -- required
  value: number | function;     -- optional (default: 0)
  hidden: bool | function;      -- optional (default: false)
  tooltip: string | function;   -- optional (default: "")
}

Ability Score

AbilityScore {
  id: string;                   -- required
  name: string | function;      -- required
  value: number | function;     -- optional (default: 0)
  modifier: number | function;  -- optional (default: 0)
  hidden: bool | function;      -- optional (default: false)
  tooltip: string | function;   -- optional (default: "")
}

Health Bar

HealthBar {
  id: string;                   -- required
  name: string | function;      -- required
  value: number | function;     -- optional (default: 0)
  max: number | function;       -- optional (default: 0)
  hidden: bool | function;      -- optional (default: false)
  tooltip: string | function;   -- optional (default: "")
}

Heading

Heading {
  id: string;                 -- required
  value: string | function;   -- required
  hidden: bool | function;    -- optional (default: false)
}

TabGroup

TabGroup {
  id: string;                   -- required
  name: string | function;      -- required
  hidden: bool | function;      -- optional (default: false)
  tooltip: string | function;   -- optional (default: "")
  ...
}

Text

Text {
  id: string;                 -- required
  value: string | function;   -- required
  hidden: bool | function;    -- optional (default: false)
}

Button

Button {
  id: string;                   -- required
  name: string | function;      -- required
  onclick: function;            -- required
  hidden: bool | function;      -- optional (default: false)
  tooltip: string | function;   -- optional (default: "")
}

Dropdown

TODO!

Dropdown {
  id: string;                   -- required
  name: string | function;      -- required
  values: [string] | function;  -- required
  selected: number              -- optional (default: 1)
  hidden: bool | function;      -- optional (default: false)
  tooltip: string | function;   -- optional (default: "")
}