World¶

Section notes in abi.h

Appended

§A world read/write & clock

§C actors (players resolve here too, via player_resolve)

§I NBT binary, KvDb (thread-safe), system & server info

Level: biome, spawn, save, weather, path, sleep (dedicated fns)

Same-toolchain fast lane, appended and struct_size-gated.

Five slots appended without touching PIER_ABI_VERSION: a pure append is not a version change, and struct_size is the precise gate.

Both directions hold. A new loader running an old mod: the old table is a byte-identical prefix of the new one, the mod cannot reach these five slots, and it works unchanged. A new mod on an old loader: SDK runtime init compares struct_size, finds the loader's table shorter than the one it was compiled against, and refuses to load. That is the right outcome, since a mod that reads the lane_publish cell on a loader without it would read out of bounds.

In short: the version number tracks "semantics changed", struct_size tracks "the table grew". This change is only the latter.

See the long comment at PierLaneDesc above. In one line: service is the cross-language (name, JSON) -> JSON channel, while this is a direct function-table call that holds only when both sides were built by the same toolchain; a fingerprint mismatch yields no pointer and the consumer falls back to service.

Server thread only.

Appended slots. Added at the tail only, guarded by struct_size.

Removing an actor and healing one already exist as actor_action's AACT_DESPAWN and AACT_HEAL. A separate slot would do the same job twice, and two implementations eventually drift.

Actor enumeration already exists as list_actors (everything in a dimension, with type names); combined with actor_get_num for positions it filters to a box. An actors_in_box slot would do the same job twice, and two implementations eventually drift.

Appended: the liquid layer (waterlogged blocks).

In Bedrock, waterlogging is not a block state but a second block in the same cell: stairs, fences or coral in the main layer and water in the liquid layer. get_block and set_block see the main layer only, so copying and pasting waterlogged stairs loses all the water: the main layer is exactly right and the other layer is missing.

These two slots expose the liquid layer. An empty layer reads back as "minecraft:air".

Appended: bulk block reads and writes

Slots¶

`spawn_particle`¶

C
bool (*spawn_particle)(int32_t dimension, PierStr effect_name, double x, double y, double z);

Spawn a particle effect at a world coordinate. Used to outline a selection box edge-by-edge. Server thread only. Returns false if the level/dimension is not ready.

Text Only
1 2 3	`dimension : 0 = overworld, 1 = nether, 2 = the end. effect_name : e.g. "minecraft:basic_flame_particle" or "minecraft:redstone_wire_dust_particle".`

Call: api->spawn_particle(dimension, effect_name, x, y, z)
Parameters:
- dimension : int32_t
- effect_name : PierStr
- x : double
- y : double
- z : double
Return type: bool
Section of abi.h: Appended
Position in the table: slot 13, counting from 0
Callers in each binding:
- Rust: World::spawn_particle
- Go: SpawnParticle, Raw.SpawnParticle

`scan_region`¶

C
bool (*scan_region)(
    int32_t dimension,
    int32_t x1,
    int32_t y1,
    int32_t z1,
    int32_t x2,
    int32_t y2,
    int32_t z2,
    void* ctx,
    PierBlockSink blocks_sink,
    PierEntitySink entities_sink
);

Scan a cuboid region, corners inclusive (order-independent). For every cell in the box, blocks_sink is called with the block name + full SNBT. For every entity whose position lies within the box, entities_sink is called with the containing cell and the entity's SNBT. Both sinks run synchronously within this call; nothing is retained afterwards. Server thread only. Returns false if the level/dimension is not ready.

Call: api->scan_region(dimension, x1, y1, z1, x2, y2, z2, ctx, blocks_sink, entities_sink)
Parameters:
- dimension : int32_t
- x1 : int32_t
- y1 : int32_t
- z1 : int32_t
- x2 : int32_t
- y2 : int32_t
- z2 : int32_t
- ctx : void*
- blocks_sink : PierBlockSink
- entities_sink : PierEntitySink
Return type: bool
Section of abi.h: Appended
Position in the table: slot 15, counting from 0
Callers in each binding:
- Rust: World::scan, World::scan_with
- Go: ScanRegion

`get_block`¶

C
bool (*get_block)(int32_t dim, int32_t x, int32_t y, int32_t z, void* ctx, PierBlockSink sink);

Read one block: sink called once with (x,y,z, type name, full SNBT).

Call: api->get_block(dim, x, y, z, ctx, sink)
Parameters:
- dim : int32_t
- x : int32_t
- y : int32_t
- z : int32_t
- ctx : void*
- sink : PierBlockSink
Return type: bool
Section of abi.h: §A world read/write & clock
Position in the table: slot 16, counting from 0
Callers in each binding:
- Rust: Block::read
- Go: GetBlock, BlockAt.Info

`set_block`¶

C
bool (*set_block)(int32_t dim, int32_t x, int32_t y, int32_t z, PierStr block_spec);

Place a block natively (BlockSource::setBlock, DEFAULT update flags). block_spec = "minecraft:stone" / "stone" (default state) or a full {name,states,...} SNBT. Unknown names fail instead of placing a placeholder.

Call: api->set_block(dim, x, y, z, block_spec)
Parameters:
- dim : int32_t
- x : int32_t
- y : int32_t
- z : int32_t
- block_spec : PierStr
Return type: bool
Section of abi.h: §A world read/write & clock
Position in the table: slot 17, counting from 0
Callers in each binding:
- Rust: Block::set
- Go: BlockAt.Set, Raw.SetBlock

`get_time`¶

C
bool (*get_time)(int64_t* out);

World time (Level::getTime).

Call: api->get_time(out)
Parameters:
- out : int64_t*
Return type: bool
Section of abi.h: §A world read/write & clock
Position in the table: slot 18, counting from 0
Callers in each binding:
- Rust: World::time
- Go: Time, Raw.GetTime

`set_time`¶

C
bool (*set_time)(int64_t t);

Set world time natively (Level::setTime).

Call: api->set_time(t)
Parameters:
- t : int64_t
Return type: bool
Section of abi.h: §A world read/write & clock
Position in the table: slot 19, counting from 0
Callers in each binding:
- Rust: World::set_time
- Go: SetTime, Raw.SetTime

`set_weather`¶

C
bool (*set_weather)(int32_t weather);

0=clear 1=rain 2=thunder, native (Level::updateWeather).

Call: api->set_weather(weather)
Parameters:
- weather : int32_t
Return type: bool
Section of abi.h: §A world read/write & clock
Position in the table: slot 20, counting from 0
Callers in each binding:
- Rust: World::set_weather
- Go: SetWeather, Raw.SetWeather

`explode`¶

C
bool (*explode)(
    int32_t dim,
    double x,
    double y,
    double z,
    float radius,
    float max_resistance,
    PierActorId source,
    bool fire,
    bool breaks_blocks,
    bool allow_underwater
);

Level::explode. source may be 0 (no source actor).

Call: api->explode(dim, x, y, z, radius, max_resistance, source, fire, breaks_blocks, allow_underwater)
Parameters:
- dim : int32_t
- x : double
- y : double
- z : double
- radius : float
- max_resistance : float
- source : PierActorId
- fire : bool
- breaks_blocks : bool
- allow_underwater : bool
Return type: bool
Section of abi.h: §C actors (players resolve here too, via player_resolve)
Position in the table: slot 38, counting from 0
Callers in each binding:
- Rust: World::explode
- Go: Explode, Raw.Explode