Build a Tamagotchi-style Item

This guide builds a small Tamagotchi-style companion. Each Item remembers its own needs. Players can feed it and play with it, its image reacts to its condition, and an optional Automation changes its needs over time.

The example is intentionally compact. Rename the variables, actions, media, and copy to fit your own idea.

1. Create the Item

Make the Item non-stackable. Remembered Item-level variables and Item::setImage() are unavailable on stackable Items.

Open the Item’s Code editor and add the shared variables and function together:

mem var hunger = 30;
mem var happiness = 70;
mem var energy = 80;

chip hungerStatus {
  config highlighted => true;
  format("Hunger: {hunger}")
}
chip happinessStatus {
  config highlighted => true;
  format("Happiness: {happiness}")
}
chip energyStatus {
  config highlighted => true;
  format("Energy: {energy}")
}

fn changeNeeds(hungerChange, happinessChange, energyChange = 0) {
  hunger = clamp(hunger + hungerChange, 0, 100);
  happiness = clamp(happiness + happinessChange, 0, 100);
  energy = clamp(energy + energyChange, 0, 100);
  happiness
}

The top-level variables and function are available to every action in this same module. Each action can call changeNeeds() instead of repeating those three calculations.

2. Add the Media Library

Upload images and name them:

• companion_happy
• companion_hungry
• companion_tired

The names let actions and Automations request an exact image.

3. Create the Feed action

Add the action below the existing declarations in Code:

action feed {
  config {
    participants: 1,
    consumes: 0,
  }

  let before = hunger;
  changeNeeds(-25, 5);

  if hunger <= 20 {
    Item::setImage(&companion_happy);
  }

  show variables hunger, happiness;
  text "@1 feeds their companion. Hunger: {before} to {hunger}.";
}

The action lowers hunger, raises happiness, changes the Item image when the need is satisfied, and shows the new values.

4. Create the Play action

Add the second action to that same Code module:

action play {
  config {
    participants: 1,
    consumes: 0,
  }

  let tooTired = energy < 15;

  if tooTired {
    show chip "Too tired" with icon => &companion_tired;
  } else {
    changeNeeds(0, 20, -15);
    Item::setImage(&companion_happy);
    show variables energy, happiness;
  }

  text if tooTired {
    "The companion is too tired to play."
  } else {
    "@1 plays with their companion!"
  }
}

The unsuccessful branch does not spend energy. The successful branch updates both remembered values.

5. Add a status Embed Template

Add this declaration to the same Code module:

embed status -> "Companion Status" {
  thumbnail: if energy < 15 then &companion_tired else if hunger > 70 then &companion_hungry else &companion_happy,
  fields: (
    format("{hunger} / 100") -> "Hunger" with progress => hunger,
    format("{happiness} / 100") -> "Happiness" with progress => happiness,
    format("{energy} / 100") -> "Energy" with progress => energy,
  ),
}

Then add a Check Status action below the others:

action checkStatus -> "Check status" {
  config {
    participants: 1,
    consumes: 0,
  }

  show embed status;
  text "@1 checks on their companion.";
}

6. Add time-based change with an App

This step is optional. Create an App, link the Item, then add an hourly Host Automation:

host automation updateCompanion {
  config {
    schedule: hourly(0),
  }

  hunger = clamp(hunger + 5, 0, 100);
  energy = clamp(energy + 10, 0, 100);

  if hunger >= 70 {
    happiness = clamp(happiness - 5, 0, 100);
    Item::setImage(&companion_hungry);
  } else if energy < 15 {
    Item::setImage(&companion_tired);
  }
}

The Host Automation runs for each linked Item. It may change that Item’s local and hosted Memory variables and its named image. It cannot change variables in the Player or App scope.

7. Test every situation

Use Sandbox Mode on each custom action. Try hunger values near 0, 20, 70, and 100. Try energy below and above 15. Confirm that every branch shows the intended image and that values remain within range.

Sandbox Mode does not save the test values, so the real companion remains untouched.

Ideas to extend it

• Add a level and experience system
• Consume a selected food Item with Item::use()
• Use the Player scope for progress shared across several companion Items
• Add rare random events with Rand::chance()
• Mutate the companion Item into a new blueprint when it evolves