Skip to main content

BTCMobs

In development: custom mobs and NPCs with skills, spawners, drop tables and quest events.

SoonEntities & models
RequiresTypeWriter0.9.0-beta-177 (BTC build)QuestRoadNetworkGUIoptionalModelEngineoptionalBetterModeloptionalMiniPlaceholdersoptionalPacketEventsoptional

In development. Entries and fields may still change before the first release.

Support
In development

BTCMobs is a Soon extension. It is not released, it has no download and no version number yet, and entries or fields may change before publication. This page documents the current development build for reference. It is not the old "BTC Mob" plugin: the mob engine now lives inside the extension itself, there is no separate plugin to install.

Overview​

BTCMobs

BTCMobs lets you build custom mobs and interactive NPCs entirely from the TypeWriter web panel. A mob template describes one creature: its base Minecraft entity, level, health, armor, skills, drops, faction, optional 3D model and optional reproduction. Spawners and natural spawns decide where and when templates appear in the world. Skills and drop tables define what the mob does and what it leaves behind.

Everything the mobs do is exposed back to TypeWriter. Events fire when a mob spawns, takes damage, casts a skill or dies. Facts and variables report health, level, count or distance. Actions spawn, despawn or make mobs cast skills. This lets quests, dialogues and cinematics react to a fight, or start one.

The same extension also provides an NPC side: a mob template can be shown as a client-side NPC, with dialogue interactions, quest objectives, camera cinematics (including cameras attached to a model bone), per-player bone visibility and ModelEngine or BetterModel animation control. The extension targets the BTC build of TypeWriter (Paper/Folia).

Features​

  • Mob templates — one btc_mob_template entry per creature: entity type, level, health, attack damage, armor, skills, drops, faction, threat table, model and animations.
  • Spawners — region-based spawners with a spawn cap, spawn cadence and warm-up that can be driven by facts, so each player can see a different pace.
  • Natural spawn replacement — swap vanilla creature spawns for BTC mobs, rule by rule, by world, biome and probability.
  • Skills — a skill is an ordered list of TypeWriter actions, or a script line. Templates attach skills to triggers such as spawn, attack, damage, death or a repeating timer.
  • Drop tables and items — vanilla materials, custom items, XP and reusable tables, with chance and quantity that scale with the mob level.
  • Quest hooks — events, facts, variables and a skill objective so stories can react to mobs and fights.
  • NPCs — template-based client-side NPCs with dialogue, interaction, look-at and camera behaviour.
  • Cinematics — spawn a mob, cast a skill, focus on an NPC or ride a model bone during a TypeWriter cinematic.
  • Persistence — skill cooldowns, counters, auras, threat tables and boss bars survive a restart when a storage artifact is configured.
  • MythicMobs import — an operator command converts a MythicMobs pack into BTCMobs pages.

Installation​

BTCMobs is in development and has no public download. The notes below describe how the development build is wired.

  1. Run the BTC build of TypeWriter (BTC Core, Paper or Folia) with the Quest and RoadNetwork extensions, which the build declares as dependencies.
  2. Put the BTCMobs JAR in plugins/Typewriter/extensions/ and restart the server. It bundles its own mob engine, so no separate BTCMobs plugin is needed.
  3. Install the optional integrations you want. The extension detects them at runtime: ModelEngine or BetterModel for 3D models, MiniPlaceholders to expose placeholders, PacketEvents, Vault, DecentHolograms and WorldGuard.
  4. To open the mob catalogue menu, the BTC GUI extension must be installed.
  5. In the web panel, create a btcmobs_storage artifact and reference it from a btcmobs_config entry (see below) so gameplay state is saved.

Getting started​

This walkthrough creates a zombie boss, spawns it in an arena and reacts to its death.

  1. In the TypeWriter web panel, open a manifest page. Add a BTCMobs Storage artifact, then a BTCMobs Global Configuration entry and set storage to that artifact.
  2. Open a static page and add a Native BTC mob template. Give it an id you will reuse (for example crypt_warden). Set entityType to ZOMBIE, display to the name players see, then level, maxHealth, attackDamage and armor.
  3. Add a Native BTC mob drop table and list its drops, one declaration per line, for example DIAMOND 1 0.25 (material, amount, chance) or exp 20to40. Reference the table by its id in the template drops list.
  4. Add a Native BTC mob skill and fill actions with the TypeWriter actions it runs, in order. In the template, add the skill id to skills, for example warden_slam~onTimer:100 to cast it every 100 ticks.
  5. Add a BTCMobs Spawner. Set mobType to the template id (not its display name), world, the two corner1 and corner2 of a region, defaultMaxMobs and defaultCooldown (in ticks).
  6. Add an On BTCMob die event with mobName set to the template id, and link its triggers to a dialogue, reward or fact modifier.
  7. Publish the pages, walk within defaultActivationRange (24 blocks by default) of the region centre, and the mob appears. Use /tw btcmobs spawners force <id> to test without waiting.
Test a mob quickly

/tw btcmobs spawn <template> <level> <amount> spawns a template next to you with the level you choose. The command suggests the loaded template ids.

How it works​

A template is only a description. A live mob is created when a spawner, a natural spawn, a Spawn a mob action or the spawn command asks for one. From then on the mob runs the skills attached to its triggers and rolls its drop declarations when it dies. Every step also raises a TypeWriter event, which is how quests and dialogues follow the fight.

Skills and triggers​

Entries in a template's skills list are written skillId or skillId~trigger. The id is the id (or name) of a btc_mob_skill entry. The trigger says when the mob runs it: onSpawn, onAttack, onDamaged, onDeath, onKill, onDespawn, onInteract, onTeleport, onExplode, onRanged, onProjectile, or onTimer:<ticks> for a repeating skill (onTimer:5s is also accepted, in seconds). A skill with no trigger runs on every trigger the mob raises, so always add one. conditions filter every skill line and targeters choose the targets they share.

Drop declarations​

Each line of a drop table, or of a template drops list, is one of:

  • a vanilla material with optional amount and chance, for example BONE 2 0.5;
  • the id or name of a btc_mob_item entry, with optional amount and chance;
  • exp 10 or exp 10to20 for experience;
  • btc:<item_id> [amount or range] [chance] [+n/m] for an item of the BTC catalogue. Without the +n/m token the quantity grows with the mob level, from x1 at level 1 to x6 at level 100;
  • the id of another drop table, which is expanded in place.

Unknown declarations are logged as warnings and skipped.

NPCs​

An NPC is a template shown to players as a client-side entity. A BtcMob NPC definition names the template in mobType and sets the display name, its offset and whether it ticks. A BtcMob NPC instance places it with spawnLocation, an optional activity, a group and extra data. NPC data entries change how the model looks: bone visibility per player, attachments that swap a bone for one from another model, ModelEngine stances for day and night, and walking speed.

Commands​

All commands live under /tw btcmobs. The short aliases /tw btc and /tw btcmobsadmin run the same tree. Every node has a permission of the form btcmobs.command.<node> (see below).

CommandDescription
/tw btcmobs mobs [list]List the loaded mob templates.
/tw btcmobs mobs listactiveList the mobs currently alive.
/tw btcmobs spawn <template> [level] [amount]Spawn a template next to you (amount 1 to 64). summon and mobs spawn are equivalent.
/tw btcmobs mobs kill <template> [radius]Kill mobs of a template around you (default radius 48).
/tw btcmobs mobs killall [radius]Kill every BTC mob around you (default radius 48).
/tw btcmobs mobs infoShow information about the mob you are looking at.
/tw btcmobs skills [list]List the loaded skills.
/tw btcmobs cast <skill>Cast a skill from yourself (skills cast, test cast and profile cast are equivalent).
/tw btcmobs spawners [list]List the spawner entries.
/tw btcmobs spawners info <id>Show one spawner.
/tw btcmobs spawners force <id> [amount]Force a spawn, ignoring conditions and caps.
/tw btcmobs spawners reloadReload the native entries.
/tw btcmobs reloadReload the native entries.
/tw btcmobs menuOpen the mob catalogue menu (first 45 templates, alphabetical).
/tw btcmobs items list and get <item> [amount]List or take an item of the catalogue.
/tw btcmobs items give <player> <item> [amount]Give a catalogue item to a player.
/tw btcmobs signal <uuid> <signal>Send a signal to an active mob.
/tw btcmobs test mechanic, condition, targeter <line>Run one script line as a test.
/tw btcmobs test on <uuid or nearest> <line>Run a script line on a specific active mob.
/tw btcmobs import mythic [path]Convert a MythicMobs pack into BTCMobs pages (default folder import/BtcMob in the TypeWriter data folder). migrate mythic is equivalent.
/tw btcmobs audit, coverage, registrydump, variables, placeholdersDiagnostics about loaded templates, skills, spawners and registries.
/tw btcmobs debug, version, modeldiagRuntime diagnostics, version and BetterModel state of nearby mobs.

Permissions​

PermissionGrants
btcmobs.command.mainThe /tw btcmobs root and its help. Granted to everyone by default.
btcmobs.command.versionversion and v. Granted to everyone by default.
btcmobs.command.mobs, .mobs.spawn, .mobs.kill, .mobs.killall, .mobs.info, .mobs.listactive, .mobs.statsThe mobs and spawn commands.
btcmobs.command.skills, .skills.castListing and casting skills.
btcmobs.command.spawners, .spawners.list, .spawners.info, .spawners.force, .spawners.reloadThe spawners commands.
btcmobs.command.items, .items.list, .items.get, .items.giveThe items commands.
btcmobs.command.menu, .menu.openThe catalogue menu.
btcmobs.command.import, .migrate, .migrate.mythic, btcmobs.importThe MythicMobs import.
btcmobs.command.test, .test.mechanic, .test.condition, .test.targeter, .test.castThe test commands.
btcmobs.command.audit, .variables, .debug, .modeldiag, .signal, .reload, .profileThe matching diagnostic commands (.profile is the profile cast alias).
btcmobs.command.admin, btcmobs.adminAdministrative root (/tw btcmobsadmin).
btcmobs.command.*, btcmobs.*All of the above.

Every permission except btcmobs.command.main and btcmobs.command.version defaults to operators only. The modeldiag command checks btcmobs.command.modeldiag, which the extension registers and grants to operators by default.

Placeholders​

Placeholders are published to MiniPlaceholders only; PlaceholderAPI is not used to publish them. The syntax is <name:argument:argument>.

PlaceholderReturns
<btcmobs_caster> and <btcmobs_caster:field>The template id, or a field of the mob bound to the player: name, type, level, hp, maxhp, percent, uuid.
<btcmobs_looking> and <btcmobs_looking:field>The same fields for the BTC mob the player is looking at (up to the look range), empty when there is none.
<btcmobs_var:name>The value of a global BTCMobs variable.
<btcmobsdamage_top:BOSS:POSITION:field>The player at a rank of a boss damage ranking. Fields: name, damage, raw_damage, percent, uuid.
<btcmobsdamage_self:BOSS:field>The viewing player's own ranking. Fields: damage, raw_damage, percent, position.
<btcmobsdamage_participants:BOSS>, _total, _max_health, _last_updateTotals for a boss damage ranking.

Entries​

57 entries, generated from the extension source.

Actions7
Events9
Objectives2
Facts9
Cinematics5
Entities2
Entity data4
Interaction bounds3
Variables8
Artifacts1
Manifests1
Definitions6

Troubleshooting​

The spawner does nothing and the log says "references unknown mob template". mobType must be the id of a btc_mob_template, not the name shown in the editor. Copy the id from the template entry. The same rule applies to btc_natural_spawn, the spawn and despawn actions, and NPC definitions.

The spawner never reaches its cap, or stops at 1. A region whose two corners are the same point caps defaultMaxMobs at 1. The cap counts mobs owned by that spawner, wherever they are. The spawner only works while a player is within defaultActivationRange of the centre of a region.

A spawner does nothing for some players. For each player near the region, the spawner checks the world, then conditionLines, then criteria, and all must pass before the region, cooldown and spawn are looked at. A player who fails criteria is skipped (a diagnostic line "criteria did not match" is logged once per player). criteria never removes a mob that has already spawned. The ...Fact fields (maxMobsFact, mobsPerSpawnFact and the others) still override the numeric defaults.

Natural spawn replacement never triggers. The entry only replaces spawns that the server already produces (natural, chunk generation or default). If the world's spawn-limits in paper-world-defaults.yml are 0, vanilla creatures never spawn and nothing is replaced. The first matching rule wins, and maxNearby set to 0 means no cap, not zero mobs.

A mob plays Attack or Death animations in a loop, or does not walk. modelAnimations only plays idle-type animations in a loop when a model is attached; attack and death names put there are ignored. One-shot animations are set in the template modelLifecycle (spawn, attack, hurt, death) and are played at the matching moment; a death animation plays to the end before the model disappears. A name missing from the model is logged once per template and that moment stays silent. Walk animations are not driven by mobs yet, only on the NPC side.

A skill or drop is silently missing. Check the server log: unknown drop declarations, unknown items and invalid chances are logged as warnings and skipped. A skills entry whose id does not match a btc_mob_skill entry is logged when the mob casts.

On BTCMob despawn does not fire. The event fires when a tracked mob leaves the world without dying (natural despawn, removal by a plugin, falling out of the world) and a player is within radius of it. It does not fire when the mob dies (use On BTCMob die), when its chunk only unloads (the mob is adopted again on reload), or when you remove it with the Despawn action or /tw btcmobs mobs kill. An empty mobName matches every mob; the same holds for the spawn, die, damage and interact events.

  • BetterModel — BetterModel is one of the two model backends (modelProvider) BTCMobs can drive for mob and NPC models.