Code frameworks

Grow Lantern into a real game

Add a choice, a derived value, a child Framework and a list to the quickstart game, and prove each step with a scenario.

Try it in the editor

Before you start

Start from the project you built in the quickstart. Each step names every file to create or change. An excerpt shows the part that changes, and you can expand it to see the whole file. After each step, choose Check and preview.

Four steps

Add a choice

Add a Calling input with two options.

schemas/keeper.json

    "calling": {
      "label": "Calling",
      "options": ["Guard", "Scout"],
      "defaultValue": "Guard"
    }

Line 11 A fixed list of choices. The default must be one of them.

The constructor takes the new input and returns it as a stored field.

rules/keeper.ts

export function construct(
  name: string,
  max_hp: number,
  calling: string,
): { name: string; max_hp: number; hp: number; calling: string } {
  return { name: name, max_hp: max_hp, hp: max_hp, calling: calling };
}

Line 4 The new input.
Lines 5-6 calling is now a stored field.

Both scenarios need the new value, in parameters and in expectedValues. Start with new-keeper.json.

scenarios/new-keeper.json

{
  "id": "new-keeper",
  "framework": "keeper",
  "parameters": { "name": "Mira", "max_hp": 10, "calling": "Guard" },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard"
  }
}

Line 4 The input you give.
Line 9 The stored value you expect.

Then make the same two changes in heal.json.

scenarios/heal.json

  "parameters": { "name": "Mira", "max_hp": 10, "calling": "Guard" },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard"
  },

Line 4 The same input.
Line 9 The same stored value.

Choose Check and preview. It should pass before you go on.

The project now holds these files. Expand any excerpt above to see its whole file.

manifest/project.json
schemas/keeper.json
rules/heal.ts
rules/hurt.ts
rules/keeper.ts
layouts/keeper.json
scenarios/heal.json
scenarios/new-keeper.json

Derive a value

A ledger function derives Guard from the calling. Declare it in the schema.

schemas/keeper.json

  "ledgerFunctions": [
    {
      "id": "guard",
      "name": "Guard",
      "field": "guard",
      "source": "rules/guard.ts"
    }
  ]

Lines 24-27 id and name identify the function, field is the stored value it fills, and source is its rules file.

Create rules/guard.ts.

rules/guard.ts

function base_guard(calling: string): number {
  return calling === "Guard" ? 3 : 1;
}

export function guard(currentValue: number, self: ElementRef): number {
  const calling: string = element.var(self, "calling") as string;
  return base_guard(calling);
}

Lines 1-3 A helper with no export.
Lines 5-7 The ledger function reads the calling and returns the derived value.

The constructor also returns a guard field, with a starting value of 0. The ledger function fills in the real value.

rules/keeper.ts

export function construct(
  name: string,
  max_hp: number,
  calling: string,
): { name: string; max_hp: number; hp: number; calling: string; guard: number } {
  return { name: name, max_hp: max_hp, hp: max_hp, calling: calling, guard: 0 };
}

Lines 5-6 guard is part of the return value, starting at 0.

A scenario checks the function. Add guard to the expected values of new-keeper.json, and a ledger line that calls the function.

scenarios/new-keeper.json

{
  "id": "new-keeper",
  "framework": "keeper",
  "parameters": { "name": "Mira", "max_hp": 10, "calling": "Guard" },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard",
    "guard": 3
  },
  "ledger": [{ "function": "guard", "currentValue": 0, "expected": 3 }]
}

Line 10 The derived value, after the ledger function ran.
Line 12 Calls the guard function with the current value 0 and expects 3.

Add the same expected value to heal.json.

scenarios/heal.json

  "parameters": { "name": "Mira", "max_hp": 10, "calling": "Guard" },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard",
    "guard": 3
  },

Line 10 The derived value stays 3 in this scenario too.

To show Guard on the sheet, list it in requiredBindings and add a text node that uses it.

layouts/keeper.json

      { "binding": "element.attributes.guard", "expectedType": "number" }

Line 15 The binding for the new field.

layouts/keeper.json

      { "kind": "text", "text": "Guard: {{element.attributes.guard}}" },

Line 32 A text node that shows the value.

Choose Check and preview. It should pass before you go on.

The project now holds these files. Expand any excerpt above to see its whole file.

manifest/project.json
schemas/keeper.json
rules/guard.ts
rules/heal.ts
rules/hurt.ts
rules/keeper.ts
layouts/keeper.json
scenarios/heal.json
scenarios/new-keeper.json

Add a child Framework

A Keeper carries a Lamp. The Lamp is a second Framework with its own schema, constructor, Frame and scenario. List its schema and its scenario in the manifest.

manifest/project.json

{
  "formatVersion": "fabled.game-project/v1",
  "projectId": "game-your-game-id",
  "projectKind": "GAME",
  "compilerProfile": "native-game-v1",
  "name": "Lantern Keepers",
  "entryFramework": "keeper",
  "frameworks": ["schemas/keeper.json", "schemas/lamp.json"],
  "scenarios": [
    "scenarios/new-keeper.json",
    "scenarios/heal.json",
    "scenarios/new-lamp.json"
  ]
}

Line 8 The Lamp schema joins the Keeper schema.
Lines 9-13 The Lamp scenario joins the Keeper scenarios.

Create the Lamp's schema.

schemas/lamp.json

{
  "id": "lamp",
  "name": "Lamp",
  "elementType": "item",
  "constructor": "rules/lamp.ts",
  "inputs": {
    "name": { "label": "Name" },
    "oil": { "label": "Oil", "defaultValue": 5 }
  },
  "frames": [{ "id": "card", "source": "layouts/lamp.json", "default": true }]
}

Lines 6-9 The inputs of the child. A child needs a name too.
Line 10 The child has its own Frame.

Create its constructor, its Frame and its scenario.

rules/lamp.ts

export function construct(name: string, oil: number): { name: string; oil: number } {
  return { name: name, oil: oil };
}

Line 1 The constructor returns the inputs as stored values.

layouts/lamp.json

{
  "version": "1.0",
  "metadata": {
    "name": "Lamp card",
    "bindingMode": "bound",
    "frameworkRef": "lamp",
    "context": "BLADE",
    "template": "standard-blade"
  },
  "dataContract": {
    "requiredBindings": [
      { "binding": "element.attributes.name", "expectedType": "string" },
      { "binding": "element.attributes.oil", "expectedType": "number" }
    ],
    "optionalBindings": [],
    "actions": [],
    "regions": []
  },
  "layout": {
    "kind": "container",
    "children": [
      { "kind": "text", "text": "{{element.attributes.name}}" },
      { "kind": "text", "text": "Oil: {{element.attributes.oil}}" }
    ]
  }
}

Lines 11-14 Every field that the Frame shows is listed as a binding.

scenarios/new-lamp.json

{
  "id": "new-lamp",
  "framework": "lamp",
  "parameters": { "name": "Lantern", "oil": 5 },
  "expectedValues": { "name": "Lantern", "oil": 5 }
}

Line 4 Builds a Lamp on its own and checks its values.

In the Keeper, a hidden input holds the Framework reference, and childFrameworks maps the slot to the Framework.

schemas/keeper.json

    "lamp": { "label": "Lamp", "defaultValue": "lamp", "hidden": true }

Line 14 A hidden input never shows in the wizard.

schemas/keeper.json

  "childFrameworks": { "lamp": "lamp" }

Line 31 Maps the slot lamp to the Framework with the id lamp.

The constructor returns the Lamp's inputs next to its own values.

rules/keeper.ts

export function construct(
  name: string,
  max_hp: number,
  calling: string,
  lamp: FrameworkRef,
): {
  values: { name: string; max_hp: number; hp: number; calling: string; guard: number };
  children: { lamp: { framework: FrameworkRef; params: { name: string; oil: number } } };
} {
  return {
    values: { name: name, max_hp: max_hp, hp: max_hp, calling: calling, guard: 0 },
    children: { lamp: { framework: lamp, params: { name: "Lantern", oil: 5 } } },
  };
}

Line 5 lamp is a FrameworkRef. The platform turns the Framework id from the input into one.
Lines 6-9 The return type lists the stored values and the child slots.
Line 12 The child slot: which Framework to build and the inputs to give it.

Give the Keeper scenarios the lamp input, and expect the Lamp that the constructor builds.

scenarios/new-keeper.json

{
  "id": "new-keeper",
  "framework": "keeper",
  "parameters": {
    "name": "Mira",
    "max_hp": 10,
    "calling": "Guard",
    "lamp": "lamp"
  },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard",
    "guard": 3
  },
  "ledger": [{ "function": "guard", "currentValue": 0, "expected": 3 }],
  "expectedChildren": { "lamp": { "name": "Lantern", "oil": 5 } }
}

Line 8 The hidden input.
Line 18 The child that the constructor builds, with its values.

scenarios/heal.json

  "parameters": {
    "name": "Mira",
    "max_hp": 10,
    "calling": "Guard",
    "lamp": "lamp"
  },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard",
    "guard": 3
  },

Line 8 The hidden input in heal.json.

scenarios/heal.json

  "expectedChildren": { "lamp": { "name": "Lantern", "oil": 5 } }

Line 30 The expected child in heal.json.

Choose Check and preview. It should pass before you go on.

The project now holds these files. Expand any excerpt above to see its whole file.

manifest/project.json
schemas/keeper.json
schemas/lamp.json
rules/guard.ts
rules/heal.ts
rules/hurt.ts
rules/keeper.ts
rules/lamp.ts
layouts/keeper.json
layouts/lamp.json
scenarios/heal.json
scenarios/new-keeper.json
scenarios/new-lamp.json

Add a list and a refused action

A list holds content that a character gains in play. The Pack holds Trinkets, a second Framework whose presets are the content. List its schema and its two scenarios in the manifest.

manifest/project.json

{
  "formatVersion": "fabled.game-project/v1",
  "projectId": "game-your-game-id",
  "projectKind": "GAME",
  "compilerProfile": "native-game-v1",
  "name": "Lantern Keepers",
  "entryFramework": "keeper",
  "frameworks": [
    "schemas/keeper.json",
    "schemas/lamp.json",
    "schemas/trinket.json"
  ],
  "scenarios": [
    "scenarios/new-keeper.json",
    "scenarios/heal.json",
    "scenarios/new-lamp.json",
    "scenarios/new-trinket.json",
    "scenarios/pack.json"
  ]
}

Lines 8-12 The Trinket schema joins the other two.
Lines 17-18 The Trinket scenario and the pack scenario.

Create the Trinket schema. Its Frame needs an id that no other Frame in the game uses.

schemas/trinket.json

{
  "id": "trinket",
  "name": "Trinket",
  "elementType": "item",
  "constructor": "rules/trinket.ts",
  "inputs": {
    "name": { "label": "Name" },
    "weight": { "label": "Weight", "defaultValue": 1, "min": 0, "max": 5 }
  },
  "frames": [
    {
      "id": "trinket-card",
      "source": "layouts/trinket.json",
      "default": true
    }
  ],
  "content": [
    {
      "id": "rope",
      "name": "Rope",
      "parameters": { "name": "Rope", "weight": 2 }
    },
    {
      "id": "anvil",
      "name": "Anvil",
      "parameters": { "name": "Anvil", "weight": 5 }
    }
  ]
}

Line 8 A weight with limits. The offer reads it.
Lines 10-16 The Trinket has its own Frame.
Lines 17-28 The presets a player can pack. Their ids are what a scenario chooses.

Create its constructor, its Frame and its scenario.

rules/trinket.ts

export function construct(
  name: string,
  weight: number,
): { name: string; weight: number } {
  return { name: name, weight: weight };
}

Line 5 Returns the two stored values.

layouts/trinket.json

{
  "version": "1.0",
  "metadata": {
    "name": "Trinket card",
    "bindingMode": "bound",
    "frameworkRef": "trinket",
    "context": "BLADE",
    "template": "standard-blade"
  },
  "dataContract": {
    "requiredBindings": [
      { "binding": "element.attributes.name", "expectedType": "string" },
      { "binding": "element.attributes.weight", "expectedType": "number" }
    ],
    "optionalBindings": [],
    "actions": [],
    "regions": []
  },
  "layout": {
    "kind": "container",
    "children": [
      { "kind": "text", "text": "{{element.attributes.name}}" },
      { "kind": "text", "text": "Weight: {{element.attributes.weight}}" }
    ]
  }
}

Lines 22-23 Shows the name and the weight.

scenarios/new-trinket.json

{
  "id": "new-trinket",
  "framework": "trinket",
  "parameters": { "name": "Rope", "weight": 2 },
  "expectedValues": { "name": "Rope", "weight": 2 }
}

Line 4 Builds a Trinket on its own and checks its values.

Declare the action and the list in the Keeper schema.

schemas/keeper.json

  "actions": [
    { "id": "hurt", "name": "Take damage", "source": "rules/hurt.ts" },
    { "id": "heal", "name": "Heal", "source": "rules/heal.ts" },
    {
      "id": "pack_trinket",
      "name": "Pack a trinket",
      "source": "rules/pack-trinket.ts"
    }
  ],

Lines 19-23 The new action.

schemas/keeper.json

  "lists": { "pack": { "label": "Pack", "of": "trinket", "max": 4 } }

Line 37 The Pack list: its label, the content Framework it holds and its size.

Create the action's rules file.

rules/pack-trinket.ts

export function pack_trinket(self: ElementRef, trinket: ContentRef): void {
  list.add(self, "pack", trinket, offer.where({ weight: { lte: 3 } }));
}

Line 1 The picked trinket arrives as a ContentRef.
Line 2 The offer decides what may be packed. Only trinkets that weigh 3 or less.

An offer can refuse, so test both outcomes. Create scenarios/pack.json.

scenarios/pack.json

{
  "id": "pack-trinkets",
  "framework": "keeper",
  "parameters": {
    "name": "Mira",
    "max_hp": 10,
    "calling": "Guard",
    "lamp": "lamp"
  },
  "expectedValues": {
    "name": "Mira",
    "max_hp": 10,
    "hp": 10,
    "calling": "Guard",
    "guard": 3
  },
  "expectedChildren": { "lamp": { "name": "Lantern", "oil": 5 } },
  "actions": [
    {
      "action": "pack_trinket",
      "parameters": {},
      "choose": { "trinket": "rope" },
      "expectedWrites": [{ "op": "list.add", "key": "pack", "value": "rope" }]
    },
    {
      "action": "pack_trinket",
      "parameters": {},
      "choose": { "trinket": "anvil" },
      "expectedRefusal": "NOT_OFFERED",
      "expectedWrites": []
    }
  ],
  "expectedLists": { "pack": ["rope"] }
}

Lines 19-24 Accepted: the rope is light enough, so it is added.
Lines 25-31 Refused: the anvil is too heavy. The step expects the refusal NOT_OFFERED and no writes.
Line 33 After the last step the Pack holds only the rope.

A Frame that shows a list uses version 2.0. Change the version, declare the action and a region in the dataContract, and draw the button and the region.

layouts/keeper.json

  "version": "2.0",

Line 2 Frames with a list use version 2.0.

layouts/keeper.json

    "actions": [
      { "name": "hurt", "functionRef": "hurt" },
      { "name": "heal", "functionRef": "heal" },
      { "name": "pack_trinket", "functionRef": "pack_trinket" }
    ],
    "regions": [{ "name": "pack", "listBinding": "element.lists.pack" }]

Line 21 The alias for the new action.
Line 23 Declares the list region.

layouts/keeper.json

      {
        "kind": "button",
        "label": "Pack a trinket",
        "actionRef": "pack_trinket"
      },
      {
        "kind": "region",
        "id": "pack_list",
        "listBinding": "{{element.lists.pack}}",
        "emptyText": "Your pack is empty."
      }

Lines 37-39 The button that runs the action.
Line 42 A region draws a list.
Line 44 The list to draw.
Line 45 Shown while the list is empty.

Choose Check and preview. It should pass before you go on.

The project now holds these files. Expand any excerpt above to see its whole file.

manifest/project.json
schemas/keeper.json
schemas/lamp.json
schemas/trinket.json
rules/guard.ts
rules/heal.ts
rules/hurt.ts
rules/keeper.ts
rules/lamp.ts
rules/pack-trinket.ts
rules/trinket.ts
layouts/keeper.json
layouts/lamp.json
layouts/trinket.json
scenarios/heal.json
scenarios/new-keeper.json
scenarios/new-lamp.json
scenarios/new-trinket.json
scenarios/pack.json

What you built

Your Keeper now has a choice, a derived value, a child Framework, a list with a refused action, and scenarios that prove each one. The recipes show smaller changes on their own.

RecipesShort task pages, starting with clamping a value.TroubleshootingWhat to do when Save, Check or Prepare fails.