Modules

A module is a folder or .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

Meta

The meta file contains the basic information of the module.

It must contain the following fields:

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

Sheet Definition

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

Packages

Modules can additionally contain multiple lua packages that can be imported using require 'packagename'. Packages should define and return a table with some shared members or functions. The package names are prefixed with their relative path from the module root, separated by . characters.

For example when using the following module:

├── meta.json
├── sheet_definition.lua
├── toplevel_package.lua
└── embedded
    └── package.lua

You can use these packages in your sheet definition:

require 'toplevel_package'
require 'embedded.package'

Lua packages are useful for separating the mechanics and structure of the character sheet by moving larger chunks of static values (e.g. long descriptions, common values, etc.) or shared functions into separate files.

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,
}

Ability Score

AbilityScore {
  id: string;
  name: string | function;
  value: number | function;
  modifier: number | function;
  hidden: bool | function;
  tooltip: string | function;
}

Button

Button {
  id: string;
  name: string | function;
  onclick: function;
  hidden: bool | function;
  tooltip: string | function;
}

Character Sheet

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

CheckBox

CheckBox {
  id: string;
  name: string | function;
  value: bool | function;
  hidden: bool | function;
  tooltip: string | function;
}

Counter

Counter {
  id: string;
  name: string | function;
  value: number | function;
  max: number | function;
  hidden: bool | function;
  tooltip: string | function;
}

Dropdown

Dropdown {
  id: string;
  name: string | function;
  options: [string] | function;
  value: number;
  hidden: bool | function;
  tooltip: string | function;
}

Heading

Heading {
  id: string;
  value: string | function;
  hidden: bool | function;
}

Health Bar

HealthBar {
  id: string;
  name: string | function;
  value: number | function;
  max: number | function;
  hidden: bool | function;
  tooltip: string | function;
}

Skill

Skill {
  id: string;
  name: string | function;
  value: number | function;
  checked: bool | function;
  max: number | function;
  hidden: bool | function;
  tooltip: string | function;
}

Slots

Slots {
  id: string;
  name: string | function;
  value: number | function;
  max: number | function;
  hidden: bool | function;
  tooltip: string | function;
}

Stat

Stat {
  id: string;
  name: string | function;
  value: number | function;
  hidden: bool | function;
  tooltip: string | function;
}

TabGroup

TabGroup {
  id: string;
  name: string | function;
  hidden: bool | function;
  tooltip: string | function;
  ...
}

Text

Text {
  id: string;
  value: string | function;
  hidden: bool | function;
}

Variable

Variable {
  id: string;
  value: number | function;
}