Skip to main content

Companion

Personal companions that follow each player as NPCs or ModelEngine models, with follow/wait and click triggers.

Freev0.10Entities & models
RequiresTypeWriter0.9Entity extensionQuest extensionBasic extensionRoadNetwork extensionModelEngineoptional
DownloadSource codeSupport

Overview​

Companion gives players a personal follower: a pet, a guide, a drone or a mascot that walks behind them wherever they go. The companion is an NPC (or a ModelEngine model) that only the owner sees, so every player can have their own without any entity being added to the real world.

You describe the companion with an entity definition you already use in TypeWriter, then attach it to an audience. Each player who enters the audience gets a companion; when they leave it, the companion disappears. A player can have several companions at once, one per entity definition.

Features​

  • Personal companions — each companion is a packet entity shown to its owner only.
  • NPC or ModelEngine — the definition can be an NPC definition or a ModelEngine model definition.
  • Follow behaviour — the companion stays between minDistance and maxDistance blocks of the player, steps over small obstacles and stays on the ground.
  • Automatic catch-up — it teleports to the player after a world change, a teleport, or when it falls far behind.
  • Walk and idle animations — on ModelEngine models, the idle and walk animations switch with the companion's movement.
  • Follow or wait — an action toggles a companion between following and standing still.
  • Click trigger — an event fires when the player right-clicks one of their companions.
  • Several at once — a player can own one companion per entity definition; summoning the same definition again replaces the old one.
  • Active count — a fact tells how many companions the player currently has.

Installation​

  1. Install the TypeWriter extensions Entity, Quest, Basic and RoadNetwork from the Extensions tab of the web panel, if they are not already installed (see the TypeWriter documentation). Companion is built against these four official extensions.
  2. Optional: install the ModelEngine extension of TypeWriter and the ModelEngine plugin if you want 3D models instead of NPCs. Companion works without them.
  3. Put the Companion JAR in plugins/Typewriter/extensions/ and restart the server.

Getting started​

Give every player a following companion:

  1. In the TypeWriter web panel, create an NPC definition (or a ModelEngine definition) for the companion: its name, skin or model.
  2. Open a manifest page and add a Companion Invocation entry.
  3. Set definition to the entity definition you created. Leave activity empty to use the default idle behaviour, or pick an entity activity if you want a custom one.
  4. Adjust minDistance (where the companion stops when the player is still) and maxDistance (how far it stays behind when the player walks). The defaults are 2.0 and 4.0.
  5. To restrict the companion to some players, add criteria, for example a fact check for a purchased pet. Leave it empty to give one to everyone in the audience.
  6. Publish. The companion appears behind the player.

To let the player stop or resume their companion, use a Companion Follow Mode action. To react to clicks, add a Companion Interact event and link the entries it should trigger, such as a dialogue or a menu.

tip

Companion Follow Mode has its own minDistance and maxDistance. When the action runs, it overwrites the distances of the companion. Keep the same values as in the invocation unless you want to change them.

How it works​

When the player enters the audience, the companion spawns behind them, at maxDistance blocks. It then moves every tick: it keeps minDistance when the player stands still and maxDistance when the player moves, and speeds up when it is far behind. It teleports next to the player when the world changes, after a teleport, when it is more than eight times maxDistance away, or when it is stuck farther than four times maxDistance.

The companion is removed when the player leaves the audience or logs out. After a world change, the companion is removed and summoned again. Companions are not saved: they are recreated from the audience each time the player joins.

Entries​

4 entries, generated from the extension source.

Actions1
Events1
Facts1
Audiences1

Troubleshooting​

The companion never appears. The entry needs a valid definition: if it is empty or deleted, nothing is summoned. The definition must be an NPC or ModelEngine definition (the field only offers those). Check also that the player matches criteria and the audience the invocation belongs to.

The companion is a plain NPC instead of my model. ModelEngine support is optional and detected at runtime. Make sure the ModelEngine extension is installed and the definition is a ModelEngine definition. Animations are looked up from the idle and walk animation names of that definition.

The companion does not move. Follow mode is toggled by each Companion Follow Mode action. If the action ran once, the companion waits; run it again to resume. Without a definition in the action, it toggles all of the player's companions.

Clicking the companion does nothing. Companion Interact only reacts to a right-click with the main hand, on the player's own companion. Check that its triggers are linked and that its criteria match.

The companion lags or floats in odd places. It walks on the ground below its position and only steps up one or two blocks. In very tight or uneven spaces it can get stuck; once it is far enough from the player, it teleports back automatically.

  • Dialog Menu — open a dialog screen when the player clicks the companion.