Skip to main content

BetterModel

BetterModel animated 3D models as TypeWriter NPCs, with animation actions, bone control and cinematics.

Paidv1.5Entities & models
RequiresTypeWriter0.9BetterModelQuest extension (TypeWriter)Basic extension (TypeWriter)Entity extension (TypeWriter)RoadNetwork extension (TypeWriter)
Buy on VoxelBuy on BuiltByBitSupport

Overview​

BetterModel connects the BetterModel plugin to TypeWriter. You design a model and its animations in Blockbench, install it in BetterModel, then use it in TypeWriter as an entity: a definition says which model to use, an instance places it in the world, and the usual TypeWriter entity machinery (audiences, activities, interactions, dialogue speakers) works on it.

Models are rendered with packets, per player, so each player can see a different state of the same NPC: other bones shown, other glow, other equipment. The extension also adds actions to play and stop animations, cinematic entries to animate models and player limbs, and a camera that rides a bone of an animated model.

Features​

  • Model entities — a definition and an instance turn any BetterModel model into an NPC with audience, activity and interaction support.
  • Automatic animations — idle, walk, strafe, jump, fly, attack, hurt and interact animations are played from the entity state, with names you can change.
  • Animation actions — play or stop an animation on a placed model from any trigger.
  • Bone control per player — show or hide bones and set glow, tint, enchant glint and brightness depending on criteria.
  • Custom hitboxes — click areas bound to bones with Hitbox, or automatic ones from hitbox bones of the model.
  • Bone replacement — swap a bone with one from another model using Attachment or Passenger.
  • Player animations — play BetterModel player-limb animations on the player with an action or in a cinematic.
  • Cinematics — drive a model from a recording with the entity cinematic and film it with the bone camera.
  • Interaction indicator — named models show an interact or dialogue indicator above their name, driven by interact objectives and interaction entries.

Installation​

  1. Install BetterModel on the server and make sure it loads your models. The bone camera needs BetterModel 2.1.0 or later; the extension is built against BetterModel 3.3.0.
  2. Install the official TypeWriter extensions Quest, Basic, Entity and RoadNetwork (the extension is built against all four).
  3. Obtain BetterModel from the stores (see the buttons above) and put the JAR in plugins/Typewriter/extensions/.
  4. Restart the server. The log shows [BetterModelExtension] BetterModel detected: initializing. If BetterModel is missing, it shows BetterModel plugin not found; extension disabled.
  5. Put your models in BetterModel and generate its resource pack as BetterModel documents. Players must have accepted the resource pack to see the models.

Getting started​

Place an animated NPC that waves when you click it:

  1. In the TypeWriter web panel, open a static page and add a BetterModel Definition. Set modelId to the name of your model in BetterModel, enable named and set displayName.
  2. In defaultAnimationSettings, check that idle, walk and interact match the animation names of your model (the defaults are idle, walk and interact).
  3. Open a manifest page and add a BetterModel Instance, set definition to the one you just created and capture spawnLocation with the position tool.
  4. Optionally add Bone Visibility in the data of the definition to hide a bone (for example a hat) from players who do not match a criteria.
  5. Add an entity interact event and a Play Entity Animation action. Set entity to the instance and animation to a custom animation name.
  6. Publish and click the NPC in game.
Hitboxes

The NPC can only be clicked where it has an interaction hitbox. Name a bone hitbox in Blockbench, or add a Hitbox entry. Without either, a single box covering the whole model is used.

How it works​

The definition holds what is shared (model, animation names, hitboxes, data). The instance holds the position, extra data and an activity. Data entries of the instance are applied after those of the definition, so an instance can override its definition.

Configuration​

The extension has no configuration file. Models, limbs and the resource pack are managed by BetterModel.

Two folders of BetterModel are used by name: entities use models registered by BetterModel, and the player actions and cinematics read player-limb models from BetterModel's players folder (for example steve, alex).

Entries​

15 entries, generated from the extension source.

Actions3
Cinematics4
Entities2
Entity data6

Troubleshooting​

The NPC is invisible. Check the log for Model '...' not found. The modelId must match a model loaded by BetterModel. When it does not, the extension tries a model called steve and, if that is also missing, spawns nothing. Also check that the player accepted the resource pack.

The NPC appears but cannot be clicked. The interaction hitbox comes from a bone whose name contains hitbox or hit_box, or from Hitbox entries. If the model has neither, one box covering the model is created, and its height is at least 1.8 blocks. Adjust hitboxYOffset in defaultAnimationSettings if the boxes float at the wrong height (default -1.6).

An animation does nothing. Animation names are those of the Blockbench model, with exact spelling. For Play Player Animation, the modelId must be a limb model from BetterModel's players folder, not a regular model.

Equipment, fire or other vanilla data have no effect. A model has no vanilla entity metadata. The log prints a one-time warning such as '...' has no BetterModel equivalent and is ignored. Main hand, off hand and helmet equipment need bones tagged ri, li and ph in Blockbench (otherwise the log says the model has no bone for that slot); armour slots are not supported. Non-uniform 3D scale uses the X value only.

The bone camera does not move. It stays where it was while the model is not visible to the player or the bone is not found. Check boneName (case-insensitive), and that either entityCinematic or instance is set; the entity cinematic wins when both are.

The model is gone after a world change or a reconnect. The extension reloads the models after join, respawn, teleport and resource pack load with short delays (up to 5 seconds). If a model stays missing, relog; cinematic models are removed on world change and when the player quits.