API versions
ApiVersion.CURRENT is 7. requireApi(n) fails the script at load when the running client is older; it cannot rescue a compile error, because a name that does not exist on the older SDK never compiles in the first place.
requireApi(2)
name("Mesh demo")
// gpu arrived in API 2; on a v1 client this file refuses to load
val format = gpu.format(VertexAttribute.floats(3), VertexAttribute.color())
val mesh = gpu.indexedMesh(format)Requiring a version
| Method | Type | Description |
|---|---|---|
ApiVersion.CURRENT |
int |
script API version of this client, currently 7 |
ApiVersion.require(minimum) |
void |
static (throws ScriptApiException when CURRENT < minimum) |
requireApi(minimum) |
Unit |
the DSL form of ApiVersion.require (throws ScriptApiException when CURRENT < minimum) |
ApiVersion has a private constructor: no instance, only the two static members, and the client appends this client provides v7 to every Unresolved reference compile error.
Packet records follow the Minecraft version, not this number — see Packets.
What each version added
API 3
| Added in 3 | Documented on |
|---|---|
combat.explosionExposure(target, source) |
Interaction |
combat.explosionDamage(target, source, power) |
Interaction |
combat.explosionDamageTaken(target, source, power) |
Interaction |
combat.damageAfterArmor(target, damage) |
Interaction |
living.visibleEffects() |
Entities and filters |
block.collisionBoxes() |
World and blocks |
block.outlineBoxes() |
World and blocks |
world.blockCollisionsIn(box) |
World and blocks |
world.isBlockSpaceFree(box) |
World and blocks |
RenderItemEvent.translate(x, y, z) |
Event list |
RenderItemEvent.rotate(degrees, axisX, axisY, axisZ) |
Event list |
RenderItemEvent.rotateX(degrees) |
Event list |
RenderItemEvent.rotateY(degrees) |
Event list |
RenderItemEvent.rotateZ(degrees) |
Event list |
RenderItemEvent.scale(x, y, z) |
Event list |
RenderItemEvent.Matrix |
Event list |
API 4
| Added in 4 | Documented on |
|---|---|
client.party() |
How a script works |
party |
Party messages |
Party |
Party messages |
PartyChannel |
Party messages |
PartyMember |
Party messages |
PartyMessage |
Party messages |
PartyShapedMessage |
Party messages |
PartyMessageKind |
Party messages |
PartyFields |
Party messages |
PartyShape |
Party messages |
PartyShapeBuilder |
Party messages |
PartyField |
Party messages |
PartyFieldType |
Party messages |
PartyWire |
Party messages |
PartyStruct |
Party messages |
PartyShapedWriter |
Party messages |
PartyPayloadWriter |
Party messages |
PartyPayloadReader |
Party messages |
PartyTarget |
Party messages |
PartyTargetKind |
Party messages |
SenderRule |
Party messages |
PartySendResult |
Party messages |
43 nursultan.dsl party helpers — shape, the field builders, send, publish, the typed field readers |
Party messages |
nursultan.party.* as a default import |
Party messages |
entity.isItem() |
Entities and filters |
entity.asItemEntity() |
Entities and filters |
ItemEntity |
Entities and filters |
API 5
| Added in 5 | Documented on |
|---|---|
party.code() |
Party messages |
PartyMember.color() |
Party messages |
PartyMember.position() |
Party messages |
PartyMember.positionAge() |
Party messages |
player.serverSprinting() |
Your player |
player.velocity(value) |
Your player |
render.pushScissor(x, y, width, height) |
2D render |
render.popScissor() |
2D render |
API 6
| Added in 6 | Documented on |
|---|---|
rotations.quantized(rotation) |
Rotations |
BackRotation |
Rotations |
BackRotation.step(from, to, tick) |
Rotations |
BackRotation.maxTicks() |
Rotations |
BackRotations |
Rotations |
BackRotations.SNAP |
Rotations |
BackRotations.INSTANT |
Rotations |
BackRotations.HUMANIZED |
Rotations |
backRotation(maxTicks) { } |
Rotations |
API 7
| Added in 7 | Documented on |
|---|---|
entity.yaw(value) |
Entities and filters |
entity.pitch(value) |
Entities and filters |
entity.velocity(value) |
Entities and filters |
entity.fallDistanceBlocks(value) |
Entities and filters |
entity.noClip() |
Entities and filters |
entity.noClip(value) |
Entities and filters |
render.blend() |
2D render |
render.blend(mode) |
2D render |
BlendMode.INVERT |
Your own geometry |
Nothing is gated per member: every addition above is present unconditionally in a client of that version, and requireApi(n) is the only check that exists.
API 1 is the surface that carries no marker at all; API 2 members are marked (API 2) in the tables of the page that documents them.
Things that no longer do anything
@NoEffect marks an element that still exists and still compiles but whose value the client never reads.
| Method | Type | Description |
|---|---|---|
NoEffect.value() |
String |
sentence saying why the element is never read |
@Retention(CLASS) — visible in the IDE and in the SDK jar, never through reflection.
Targets: type, method, field, parameter, record component.
What is marked
| Member | Type | Description |
|---|---|---|
Priority |
enum |
whole type marked, five constants kept so old scripts compile (no effect on dispatch order) |
EventOptions.priority() |
Priority |
record component and its accessor (deprecated) (no effect: the value is never read) |
EventOptions.priority(priority) |
EventOptions |
copy of DEFAULT carrying the value (deprecated) (no effect: the value is never read) |
ScriptScope.on<E>(priority, ignoreCancelled) { } |
Subscription |
discards the argument (deprecated, drop the argument) |
ScriptScope.on(type, priority, ignoreCancelled) { } |
Subscription |
discards the argument (deprecated, drop the argument) |
EntryScope.on<E>(priority, ignoreCancelled) { } |
Subscription |
discards the argument (deprecated, drop the argument) |
EntryScope.on(type, priority, ignoreCancelled) { } |
Subscription |
discards the argument (deprecated, drop the argument) |
RotationOptions.clientSide() |
boolean |
record component and its accessor (deprecated) (no effect: the rotation always reaches the server) |
RotationOptions.clientSide(value) |
RotationOptions |
copy carrying the value (deprecated) (no effect: the rotation always reaches the server) |
RotationOptions.normalizeMouseMovement() |
boolean |
record component and its accessor (deprecated, use rotations.quantized) (no effect: the value is never read) |
RotationOptions.normalizeMouseMovement(value) |
RotationOptions |
copy carrying the value (deprecated, use rotations.quantized) (no effect: the value is never read) |
All eleven still compile and still store what you give them; nothing reads the stored value.
The order that replaced Priority is on Subscribing, the two rotation flags on Rotations.
Every one of them raises a compile warning in the script console, with the line it sits on.
Deprecated but still working
| Member | Type | Description |
|---|---|---|
RotationOptions.smoothBackRotation() |
boolean |
record component and its accessor (deprecated, use backRotation) |
RotationOptions.smoothBackRotation(value) |
RotationOptions |
true turns a SNAP return into HUMANIZED (deprecated, use backRotation) |
BackRotation.FAST |
BackRotation |
the return BackRotations.SNAP gives (deprecated, use BackRotations.SNAP) |
BackRotation.SMOOTH |
BackRotation |
the return BackRotations.HUMANIZED gives (deprecated, use BackRotations.HUMANIZED) |
These four are aliases, not stubs: they kept their old shape of return when API 6 rewrote it, so a script written before it behaves the same.
What a bump costs
The SDK api jar is named nursultan-script-api-v<N>.jar, so an update drops in a new file and rewrites build.gradle.kts to point at it; IDEA re-syncs the project once.
ApiVersion.CURRENT is part of the compile-cache key, so a bump invalidates every cached compiled script and forces a full recompile on the first launch after the update.
Last updated