Link Module

Link module (companion app)

NeroCreatures can show your bestiary, your pets and the boss fight you are in to a Neroland companion app. It does that through Neroland Core's link API: NeroCreatures registers what it can show and what it can do, and a separate bridge mod serves that to your paired app over your own network.

NeroCreatures itself ships no server, no HTTP, no accounts and no outbound connection. It only fills in a registry entry inside Core. With no bridge mod installed, the link module does nothing at all.

What it exposes

Kind	Name	What it is
Section	bestiary	The whole creature roster, with your kill count for each
Section	pets	Your tamed pets and deployed drones, with their caps
Section	bosses	Summoned boss fights in progress, with your contribution
Action	pet_recall	Bring your own pets to you
Event	pet_state_changed	One of your creatures was tamed, released, deployed, recalled or died
Event	boss_phase	A boss fight escalated (broadcast)
Event	boss_defeated	A boss fight ended in the boss's defeat (broadcast)
Alert	your pet died	Raised for the owner
Alert	a boss you fought was defeated	Raised for each participant of a summoned fight

Module id nerocreatures, schema version 1. The schema version is bumped whenever the shape of a section changes, so an app can tell what it is parsing.

Section: bestiary

{
  "schema_version": 1,
  "player_online": true,
  "total_kills": 41,
  "species_killed": 5,
  "spawns_enabled": true,
  "creatures": [
    {
      "id": "nerocreatures:void_crawler",
      "name": "Void Crawler",
      "translation_key": "entity.nerocreatures.void_crawler",
      "killed": 12,
      "spawns": [
        { "biome_tag": "neroland:space/dark_biomes", "weight": 30,
          "group_min": 1, "group_max": 2 }
      ]
    }
  ]
}

Kill counts come from vanilla's own statistics — the same minecraft:killed numbers on your statistics screen — not from a NeroCreatures store. That is deliberate: a bestiary with its own store would be a third player-keyed record to erase, retain and declare, in exchange for a number the game already keeps.

The one consequence is that kill counts need you to be online, because vanilla's stats counter is loaded with you. While you are offline the roster and its spawn data still come back — those are facts about the world — and player_online is false, so an app can say why the numbers are missing rather than showing zeroes as though you had never killed anything.

A creature with an empty spawns array never spawns naturally (the Terraforming Drone).

Section: pets

{
  "schema_version": 1,
  "player_online": true,
  "caps": { "pets": { "used": 2, "max": 3 }, "drones": { "used": 1, "max": 2 } },
  "pets": [
    { "entity": "…", "kind": "pet", "type": "nerocreatures:glacite_wisp",
      "name": "Glacite Wisp", "dimension": "nerospace:glacira",
      "status": "loaded", "health": 8.0, "max_health": 12.0, "command": "follow" },
    { "entity": "…", "kind": "drone", "type": "nerocreatures:terraforming_drone",
      "name": "Terraforming Drone", "dimension": "nerospace:greenxertz",
      "status": "unloaded" }
  ]
}

Your own rows and nobody else's. status is loaded when the creature happens to be in a loaded chunk — answered with a single lookup in the level's entity index, so an unloaded pet simply reads as unloaded rather than being dragged into memory to be described.

There are no coordinates, here or in the store behind it. The dimension is present because that is what the ownership index holds (so an erase request knows which level to look in); where your pets are is not something NeroCreatures records. See Pets & Drones.

Section: bosses

{
  "schema_version": 1,
  "player_online": true,
  "fights": [
    { "fight": "…", "boss": "nerocreatures:cinder_tyrant", "name": "Cinder Tyrant",
      "dimension": "nerospace:cindara", "phase": 2, "phase_count": 3, "health": 0.41,
      "your_damage": 184.5, "your_share": 0.37, "participants": 3 }
  ]
}

Only summoned fights appear, because only summoned fights exist as fights: a boss you find in the world is a mob, not an event, and records nothing about anybody (Bosses).

your_damage and your_share are yours alone, and read 0 for a fight you have not touched. There is no participant list — participants is a count, so an app can say "you and two others" without knowing who they are. your_share is your damage over the fight's total, which is an aggregate of the fight rather than a fact about any identifiable other player.

Any section name other than these three returns an empty object.

Action: pet_recall

{}                                       // recall all of your pets
{ "pet": "<creature UUID>" }             // recall one

Brings your own tamed pets to where you are standing. Each pet is placed on a valid block near you — solid ground, open air, room to stand, found by a small bounded search — so a recall never puts an animal inside a wall or over a drop. A pet's standing order is preserved and re-applied, so a guarding pet guards its new spot rather than walking back to the old one.

{ "schema_version": 1, "recalled": 1,
  "pets": [ { "entity": "…", "type": "nerocreatures:glacite_wisp",
              "name": "Glacite Wisp", "command": "follow" } ],
  "skipped": [ { "entity": "…", "type": "…", "reason": "other_dimension" } ] }

reason is one of other_dimension, not_loaded or no_room.

Drones are never recalled by this action, and that is not an oversight: a drone's whole purpose is the area it was deployed to work, and teleporting it to you would quietly break it. Folding a drone away stays a deliberate in-world act (sneak-interact with an empty hand).

Refusals use Core's shared action error codes:

Code	When
PLAYER_OFFLINE_REQUIRED	You are not online (see below)
NOT_OWNER	The pet id is not one of your own creatures
VALIDATION	Malformed pet id, you have no pets, or none could be recalled
INTERNAL	No world is running, or something went wrong server-side

A pet that belongs to somebody else answers exactly like a creature that does not exist, so the action cannot be used to probe for other players' pets.

pet_recall is online-only, permanently. A recall moves an animal to where its owner is standing, and an offline player is not standing anywhere; there is no sensible offline semantics to add later.

Why only one action

Everything else an app might want to do to a creature — taming, commanding, deploying a drone, summoning a boss — is an in-world act with an in-world cost and an in-world audience. Doing any of those from a phone would let a player affect the world without being in it. Recalling a pet you already own to a place you are already standing changes nothing that was not already yours, which is what makes it the one safe write.

Events

Topic	Scope	Payload
pet_state_changed	Your session	entity, kind, type, name, dimension, state, timestamp
boss_phase	Broadcast	boss, name, dimension, phase, phase_count, summoned, timestamp
boss_defeated	Broadcast	as above, plus participants

state is one of tamed, released, deployed, recalled or died.

Broadcasts carry no player data at all. A boss event reaches every session, so it says which boss, how far the fight got and where — a place, not a person. There is no participant list, no killer and no position, which is the same rule Core's ThresholdEvents contract imposes on the nerocreatures:boss_pressure channel.

Alerts

Two, and deliberately only two. A Core alert survives until it is acknowledged, so it is reserved for things worth telling you about while the game is closed.

Alert	Severity	Raised for	Text
Your pet died	WARN	The owner	"Your Glacite Wisp did not survive."
A boss you fought was defeated	INFO	Each recorded participant of a summoned fight	"The Cinder Tyrant you fought has been defeated."

Alert text names a creature or a boss and nothing else — never who killed it, never who else was in the fight. A natural boss records no participants, so it alerts nobody.

Alerts are stored by Core under your UUID and are purged by the same shared erasure request that clears everything else.

Privacy

(See also ../PRIVACY.md and Data storage.)

• Your own data only. Every section is scoped to your player id before it leaves the mod: your kill counts, your ownership rows, your contribution. No other player's rows, shares, names, UUIDs or positions appear in a snapshot, an action result, an event payload or an alert.
• No coordinates. The mod stores none, so the link cannot leak any.
• The link adds no stored data. Every read goes to a store that already exists, which is also why erasure needs no extra wiring: a player erased through Core's shared hook immediately reads as owning nothing and having contributed nothing.
• Consent lives with the bridge. Whether an app may connect at all, and which of your data it receives, is governed by the bridge mod's pairing — NeroCreatures only answers questions the bridge is already authorised to ask.

Notes for server admins

• The link module is server-side only and starts with the world. Nothing is exposed until a bridge mod is installed and an app has been paired with it.
• Creature data reaches an app read-only apart from the single pet_recall action. There is no way to spawn, tame, summon or configure anything through the link — those stay operator commands (see Commands).
• If the link module fails to register for any reason, it is logged as a warning and the mod carries on. Creatures do not depend on it.

See also

• Pets & Drones — what the pets section is describing
• Bosses — the two entry modes, and the threshold channel other mods listen to
• Data storage — the stores behind all of this, and how to erase them
• Commands — the operator-side equivalents