Skript AddonBetterModel 3.xPaper 1.21.x⚠ Alpha release

Build BetterModel systems in Skript.

SkBetterModels brings BetterModel's model, tracker, animation, bone, hitbox and player-limb APIs into Skript — giving server developers a native-feeling scripting layer without writing Java for every integration.

Get started →Browse reference

28Effects

7Conditions

19Events

41Expression registrations

4Sections

8Custom types

Setup

Installation

SkBetterModels is an addon for Skript and BetterModel. Install the dependencies first, then place the addon in your server's /plugins directory.

Required · Skript 2.16+

Required · BetterModel 3.x

Platform · Paper API 1.21.11

Optional · Citizens 2.0.35+

01 · Install dependencies

Install Skript and BetterModel on the server before adding SkBetterModels.

02 · Add SkBetterModels

Drop SkBetterModels-0.1.1-alpha.jar into /plugins.

03 · Restart the server

Use a full restart so Skript, BetterModel and the addon initialize in a clean order.

04 · Start scripting

Once the addon enables, its BetterModel types and syntax become available to Skript.

Dependency behavior

The plugin declares Skript and BetterModel as hard dependencies and Citizens as a soft dependency. It also checks for Skript 2.16+ and BetterModel 3.x during startup.

Core API

Custom types

These are the main values used throughout the syntax reference.

Type	Skript type token	Purpose
BetterModel Tracker	`%bettermodeltracker%`	General tracker interface. Works with entity and dummy trackers.
BetterModel Model	`%bettermodelmodel%`	Loaded BetterModel renderer/model definition.
BetterModel Bone	`%bettermodelbone%`	A rendered bone from a live model.
BetterModel Animation	`%bettermodelanimation%`	An animation definition from a model blueprint.
BetterModel Running Animation	`%bettermodelrunninganimation%`	A currently running animation.
BetterModel Animation Modifier	`%bettermodelanimationmodifier%`	Animation playback settings such as speed, range and override.
BetterModel Player Limb	`%bettermodelplayerlimb%`	A player-limb selector used by the player animation system.
BetterModel Entity Tracker	`%bettermodelentitytracker%`	An entity-backed BetterModel tracker.

Reference · 28 classes

Effects

Effects perform an operation. The patterns below are the registered Skript syntax in the current source.

Attach Model

Effect

Creates a BetterModel entity tracker for entities using a model name.

attach model %string% to %entities%

Play Animation

Effect

Plays a named animation on an entity's BetterModel.

play bettermodel animation %string% on %entity%

Play Animation · Modified

Effect

Advanced playback with optional speed, start/end range, override mode, playback type and affected bones.

play bettermodel animation %string% for %bettermodeltracker% [with speed %number%] [from %number% to %number%] [with override %-boolean%] [as %-string%] [on bones %string%]

Play Limb Animation

Effect

Plays a player-limb animation on model entities.

play limb animation %string% on model %entities%

Player Animation

Effect

play player animation %string% on %players% stop player animation %string% on %players%

Stop All Player Animations

Effect

stop all player animations on %players%

Stop Animation

Effect

stop [the] bettermodel animation %string% (of|for|from) %bettermodeltracker% stop [the] bettermodel animation %string% (of|for|from) %entity%

Default State

Effect

set default state of model %entities% to %string%

Part Visibility

Effect

set part %string% of model %entities% to (visible|hidden)

Change Part

Effect

change part %string% of model %entities% to %string%

Hide / Show Model

Effect

hide model %entities% from %players% show model %entities% to %players%

Tint / Glow / Brightness

Effect

set tint of model %entities% to %color% set glow of model %entities% to %boolean% set brightness of model %entities% to %number%

Enchant Glint

Effect

apply enchant glint to model %entities% remove enchant glint from model %entities%

Body Rotation

Effect

set body rotation of model %entities% to %number% set body rotation limits of %bettermodeltracker% to %number% and %number% body, %number% and %number% head set body rotation behavior of %bettermodeltracker% to %boolean% body uneven and %boolean% head uneven set body rotation timing of %bettermodeltracker% to %number% delay and %number% duration lock body rotation of %bettermodeltracker% unlock body rotation of %bettermodeltracker%

Tracker Offset

Effect

set [bettermodel] tracker offset of %bettermodeltracker% to %vector% set [bettermodel] tracker offset of %entity% to %vector%

Bind Hitbox

Effect

bind hitbox %string% to model %entities%

Mount / Dismount

Effect

mount %entity% to model %entity% dismount %entity% from model %entity% dismount all from model %entity%

Close / Despawn Entity Tracker

Effect

close entity tracker %bettermodelentitytracker% despawn entity tracker %bettermodelentitytracker%

Spawn Dummy Model

Effect

spawn model %string% at %location%

Disguise / Undisguise

Effect

disguise %player% as bettermodel %bettermodeltracker% undisguise %player% from bettermodel %bettermodeltracker%

Lock / Unlock Model

Effect

lock model %entities% unlock model %entities%

Pair / Unpair Model

Effect

pair model %entity% with %entity% unpair model %entity%

Set Player Limb of Bone

Effect

set player limb of %bettermodelbone% to %bettermodelplayerlimb%

Citizens Model

Effect

Requires Citizens.

set model of citizen %number% to %string%

Reference · 7

Conditions

Use these in if statements, event guards and other conditional contexts.

Entity Tracker Valid

Condition

entity tracker %bettermodelentitytracker% is valid entity tracker %bettermodelentitytracker% (isn't|is not) valid

Model Is

Condition

model %entities% (is|are) %string% model %entities% (isn't|aren't) %string%

Model Hidden From

Condition

model %entity% is hidden from %player% model %entity% (isn't|is not) hidden from %player%

Model Locked

Condition

model %entities% is locked model %entities% (isn't|is not) locked

Model Paired

Condition

model %entities% is paired model %entities% (isn't|is not) paired

Part Visible

Condition

model part %string% of %entity% is visible

Player Has Active Animations

Condition

%players% has active player animations

Reference · 19

Events

These triggers expose BetterModel lifecycle, animation, hitbox and tracker activity to Skript.

Async Tick

Event

every [1¦%-number%] async tick[s] every %number% async second[s]

BetterModel Animation Play

Event

bettermodel animation play

BetterModel Animation End

Event

bettermodel animation end

BetterModel Animation Signal

Event

bettermodel animation signal

BetterModel Limb Animation Play

Event

on bettermodel limb animation play

BetterModel Hitbox Enter

Event

bettermodel hitbox enter

BetterModel Hitbox Exit

Event

bettermodel hitbox exit

BetterModel Hitbox Interact

Event

bettermodel hitbox interact

BetterModel Spawn

Event

bettermodel spawn

Tracker Create / Close

Event

bettermodel tracker create bettermodel tracker close

Dummy Tracker Create

Event

bettermodel dummy tracker (create|spawn)

Tracker Show / Hide

Event

bettermodel tracker show [for player] bettermodel tracker hide [for player]

Model Spawn / Despawn At Player

Event

bettermodel model spawn[ing] at player bettermodel model despawn[ing] at player

Model Despawn

Event

bettermodel model despawn

BetterModel Reload Start / End

Event

bettermodel reload start[ing] bettermodel reload end[ing]

Reference · 41 registrations

Expressions

Expressions return BetterModel objects or properties. Several are changeable and can be assigned with set.

Trackers & models

Entity Tracker

Expression

[the] entity tracker of %entity%

All Entity Trackers

Expression

all [(of the)] entity trackers

Last Created Entity Tracker

Expression

last created entity tracker

Last Created Tracker

Expression

last created [bettermodel] tracker

All BetterModel Models

Expression

[all] bettermodel models

Model Name

Expression

model of %entity% %entity%'s model

Model Partner

Expression

model partner of %entity%

Bones & parts

Bone

Expression

bone %string% of %bettermodeltracker% the bone %string% of %bettermodeltracker%

All Bones

Expression

[all] bones of %bettermodeltracker%

Bone Names of Model

Expression

[all] bone names of model %string%

Bone Position

Expression

position of %bettermodelbone%

Bone Rotation

Expression

rotation of bone %string% of %entity%

Bone Scale

Expression

scale of bone %string% of %entity%

Bone Visibility

Expression

visibility of %bettermodelbone% bone visibility of %bettermodelbone%

Bone Enchanted State

Expression

bone enchanted state of %string% of %entity%

Animations & modifiers

Model Animations

Expression

[all] animations of model %string%

Tracker Animations

Expression

[all] animations of %bettermodeltracker%

Animation by Name

Expression

animation %string% of %bettermodeltracker%

Running Animation

Expression

active animation of %bettermodeltracker% running animations of %bettermodeltracker%

Animation Name / Length

Expression

name of %bettermodelanimation% length of %bettermodelanimation%

Modifier Properties

Expression

start of %bettermodelanimationmodifier% end of %bettermodelanimationmodifier% speed of %bettermodelanimationmodifier% override of %bettermodelanimationmodifier%

Tracker & render properties

Body Rotation Properties

Expression

min body rotation of %bettermodeltracker% max body rotation of %bettermodeltracker% min head rotation of %bettermodeltracker% max head rotation of %bettermodeltracker% rotation delay of %bettermodeltracker% rotation duration of %bettermodeltracker%

Tracker Offset

Expression

tracker offset of %bettermodeltracker%

Tracker Billboard

Expression

billboard of %bettermodeltracker% tracker billboard of %bettermodeltracker%

Model Glow / Glow Colour

Expression

model glow of %entity% model glow colo[u]r of %entity%

Model Scale

Expression

model scale of %entity%

Model View Range

Expression

model view range of %entity%

Player limbs & event values

Player Limb

Expression

player limb %string% [all] bettermodel player limbs

Event Model / Animation

Expression

event-model event-animation

Reference · 4

Sections

Sections are multi-line Skript blocks.

Play BetterModel Animation

Section

play bettermodel animation %string% for %bettermodeltracker%:

Supports nested modifier entries used by the animation section's builder.

Run Async

Section

run async:

Run Task Sync

Section

run task (sync|synchronously):

Async Loop Range

Section

async loop %number% to %number%:

Important

Async & threading

SkBetterModels exposes asynchronous script execution. The addon also provides a synchronous handoff section for code that needs the main server thread.

Main-thread rule

Do not assume Bukkit, world, entity or BetterModel operations are safe from an async section. Use run task sync: for operations that must execute on the server thread.

Async

run async:, async loop ...: and the async tick event execute script code away from the normal server thread.

Sync handoff

run task sync: executes its nested body on the main thread.

Optional integration

Citizens

Citizens support is optional. The current addon exposes a dedicated effect for setting a BetterModel model on a Citizens NPC.

Citizens syntax

set model of citizen %number% to %string%

Compatibility

Supported environment

The current project is built and declared against the following dependencies.

Component	Current target
Skript	2.16.1 at compile time · minimum 2.16
BetterModel	3.4.1 at compile time · plugin check accepts 3.x
Paper	1.21.11 API
Citizens	2.0.35-SNAPSHOT API · soft dependency
Java	25 toolchain

Alpha status

This is v0.1.1-alpha. Syntax and implementation details may change between releases. Test updates on a development server before moving them to production.