247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
# Auxiliary aspects
|
|
|
|
Collection of other methods that control smaller, yet still important aspects of the game
|
|
|
|
## Sounds
|
|
|
|
### `sound(name, pos, volume?, pitch?)`
|
|
|
|
Plays a specific sound `name`, at block or position `pos`, with optional `volume` and modified `pitch`. `pos` can be
|
|
either a block, triple of coords, or a list of thee numbers. Uses the same options as a corresponding `playsound` command.
|
|
|
|
## Particles
|
|
|
|
### `particle(name, pos, count?. spread?, speed?, playername?)`
|
|
|
|
Renders a cloud of particles `name` centered around `pos` position, by default `count` 10 of them, default `speed`
|
|
of 0, and to all players nearby, but these options can be changed via optional arguments. Follow vanilla `/particle`
|
|
command on details on those options. Valid particle names are
|
|
for example `'angry_villager', 'item diamond', 'block stone', 'dust 0.8 0.1 0.1 4'`.
|
|
|
|
### `particle_line(name, pos, pos2, density?)`
|
|
|
|
Renders a line of particles from point `pos` to `pos2` with supplied density (defaults to 1), which indicates how far
|
|
apart you would want particles to appear, so `0.1` means one every 10cm.
|
|
|
|
### `particle_rect(name, pos, pos2, density?)`
|
|
|
|
Renders a cuboid of particles between point `pos` to `pos2` with supplied density.
|
|
|
|
## Markers
|
|
|
|
### `create_marker(text, pos, rotation?, block?)`
|
|
|
|
Spawns a (permanent) marker entity with text or block at position. Returns that entity for further manipulations.
|
|
Unloading the app that spawned them will cause all the markers from the loaded portion of the world to be removed.
|
|
Also - if the game loads that marker in the future and the app is not loaded, it will be removed as well.
|
|
|
|
### `remove_all_markers()`
|
|
|
|
Removes all scarpet markers from the loaded portion of the world created by this app, in case you didn't want to do
|
|
the proper cleanup.
|
|
|
|
## System function
|
|
|
|
### `nbt(expr)`
|
|
|
|
Treats the argument as a nbt serializable string and returns its nbt value. In case nbt is not in a correct nbt
|
|
compound tag format, it will return `null` value.
|
|
|
|
Consult section about container operations in `Expression` to learn about possible operations on nbt values.
|
|
|
|
### `escape_nbt(expr)`
|
|
|
|
Excapes all the special characters in the string or nbt tag and returns a string that can be stored in nbt directly
|
|
as a string value.
|
|
|
|
### `print(expr)`
|
|
|
|
Displays the result of the expression to the chat. Overrides default `scarpet` behaviour of sending everyting to stderr.
|
|
|
|
### `logger(expr)`
|
|
|
|
Prints the message to system logs, and not to chat.
|
|
|
|
### `run(expr)`
|
|
|
|
Runs a vanilla command from the string result of the `expr` and returns its success count
|
|
|
|
<pre>
|
|
run('fill 1 1 1 10 10 10 air') -> 123 // 123 block were filled, this operation was successful 123 times out of a possible 1000 blocks volume
|
|
run('give @s stone 4') -> 1 // this operation was successful once
|
|
</pre>
|
|
|
|
### `save()`
|
|
|
|
Performs autosave, saves all chunks, player data, etc. Useful for programs where autosave is disabled due to
|
|
performance reasons and saves the world only on demand.
|
|
|
|
### `load_app_data(), load_app_data(file)`
|
|
|
|
Loads the app data associated with the app from the world /scripts folder. Without argument returns the memory
|
|
managed and buffered / throttled NBT tag. With a file name - reads explicitly a file with that name from the
|
|
scripts folder.
|
|
|
|
You can use app data to save non-vanilla information separately from the world and other scripts.
|
|
|
|
### `store_app_data(tag), store_app_data(tag, file)`
|
|
|
|
Stores the app data associated with the app from the world /scripts folder. With the `file` parameter saves
|
|
immediately and with every call, without `file` parameter, it may take up to 10 seconds for the output file
|
|
to sync preventing flickering in case this tag changes frequently. It will be synced when server closes.
|
|
|
|
### `tick_time()`
|
|
|
|
Returns game tick counter. Can be used to run certain operations every n-th ticks, or to count in-game time
|
|
|
|
### `game_tick(mstime?)`
|
|
|
|
Causes game to run for one tick. By default runs it and returns control to the program, but can optionally
|
|
accept expected tick length, in milliseconds. You can't use it to permanently change the game speed, but setting
|
|
longer commands with custom tick speeds can be interrupted via `/script stop` command
|
|
|
|
<pre>
|
|
loop(1000,game_tick()) // runs the game as fast as it can for 1000 ticks
|
|
loop(1000,game_tick(100)) // runs the game twice as slow for 1000 ticks
|
|
</pre>
|
|
|
|
### `seed()`
|
|
|
|
Returns current world seed.
|
|
|
|
### `current_dimension()`
|
|
|
|
Returns current dimension that the script runs in.
|
|
|
|
### `in_dimension(smth, expr)`
|
|
|
|
Evaluates the expression `expr` with different dimension execution context. `smth` can be an entity,
|
|
world-localized block, so not `block('stone')`, or a string representing a dimension like:
|
|
`'nether'`, `'the_nether'`, `'end'` or `'overworld'`, etc.
|
|
|
|
### `schedule(delay, function, args...)`
|
|
|
|
Schedules a user defined function to run with a specified `delay` ticks of delay. Scheduled functions run at the end
|
|
of the tick, and they will run in order they were scheduled.
|
|
|
|
### `statistic(player, category, entry)`
|
|
|
|
Queries in-game statistics for certain values. Categories include:
|
|
|
|
* `mined`: blocks mined
|
|
* `crafted`: items crafted
|
|
* `used`: items used
|
|
* `broken`: items broken
|
|
* `picked_up`: items picked up
|
|
* `dropped`: items dropped
|
|
* `killed`: mobs killed
|
|
* `killed_by`: blocks mined
|
|
* `custom`: various random stats
|
|
|
|
For the options of `entry`, consult your statistics page, or give it a guess.
|
|
|
|
The call will return `null` if the statistics options are incorrect, or player didn't get these in their history.
|
|
If the player encountered the statistic, or game created for him empty one, it will return a number.
|
|
Scarpet will not affect the entries of the statistics, even if it is just creating empty ones. With `null` response
|
|
it could either mean your input is wrong, or statistic has effectively a value of `0`.
|
|
|
|
### `plop(pos, what)`
|
|
|
|
Plops a structure or a feature at a given `pos`, so block, triple position coordinates or a list of coordinates.
|
|
To `what` gets plopped and exactly where it often depends on the feature or structure itself. For example, all
|
|
structures are chunk aligned, and often span multiple chunks. Repeated calls to plop a structure in the same chunk
|
|
would result either in the same structure generated on top of each other, or with different state, but same position.
|
|
Most structures generate at specific altitudes, which are hardcoded, or with certain blocks around them. API will
|
|
cancel all extra position / biome / random requirements for structure / feature placement, but some hardcoded
|
|
limitations may still cause some of structures/features not to place. Some features require special blocks to be
|
|
present, like coral -> water or ice spikes -> snow block, and for some features, like fossils, placement is all sorts
|
|
of messed up. This can be partially avoided for structures by setting their structure information via `set_structure`,
|
|
which sets it without looking into world blocks, and then use `plop` to fill it with blocks. This may, or may not work.
|
|
|
|
All generated structures will retain their properties, like mob spawning, however in many cases the world / dimension
|
|
itself has certain rules to spawn mobs, like plopping a nether fortress in the overworld will not spawn nether mobs,
|
|
because nether mobs can spawn only in the nether, but plopped in the nether - will behave like a valid nether fortress.
|
|
|
|
`plop` will not use world random number generator to generate structures and features, but its own. This has a benefit
|
|
that they will generate properly randomly, not the same time every time.
|
|
|
|
Structure list:
|
|
|
|
* `monument`: Ocean Monument. Generates at fixed Y coordinate, surrounds itself with water.
|
|
* `fortress`: Nether Fortress. Altitude varies, but its bounded by the code.
|
|
* `mansion`: Woodland Mansion
|
|
* `jungle_temple`: Jungle Temple
|
|
* `desert_temple`: Desert Temple. Generates at fixed Y altitude.
|
|
* `end_city`: End City with Shulkers
|
|
* `igloo`: Igloo
|
|
* `shipwreck`: Shipwreck, version1?
|
|
* `shipwreck2`: Shipwreck, version2?
|
|
* `witch_hut`
|
|
* `ocean_ruin`, `ocean_ruin_small`, `ocean_ruin_tall`: Stone variants of ocean ruins.
|
|
* `ocean_ruin_warm`, `ocean_ruin_warm_small`, `ocean_ruin_warm_tall`: Sandstone variants of ocean ruins.
|
|
* `treasure`: A treasure chest. Yes, its a whole structure.
|
|
* `pillager_outpost`: A pillager outpost.
|
|
* `mineshaft`: A mineshaft.
|
|
* `mineshaft_mesa`: A Mesa (Badlands) version of a mineshaft.
|
|
* `village`: Plains, oak village.
|
|
* `village_desert`: Desert, sandstone village.
|
|
* `village_savanna`: Savanna, acacia village.
|
|
* `village_taiga`: Taiga, spruce village.
|
|
* `village_snowy`: Resolute, Canada.
|
|
|
|
Feature list:
|
|
|
|
* `oak`
|
|
* `oak_beehive`: oak with a hive (1.15+).
|
|
* `oak_large`: oak with branches.
|
|
* `oak_large_beehive`: oak with branches and a beehive (1.15+).
|
|
* `birch`
|
|
* `birch_large`: tall variant of birch tree.
|
|
* `shrub`: low bushes that grow in jungles.
|
|
* `shrub_acacia`: low bush but configured with acacia (1.14 only)
|
|
* `shrub_snowy`: low bush with white blocks (1.14 only)
|
|
* `jungle`: a tree
|
|
* `jungle_large`: 2x2 jungle tree
|
|
* `spruce`
|
|
* `spruce_large`: 2x2 spruce tree
|
|
* `pine`: spruce with minimal leafage (1.15+)
|
|
* `pine_large`: 2x2 spruce with minimal leafage (1.15+)
|
|
* `spruce_matchstick`: see 1.15 pine (1.14 only).
|
|
* `spruce_matchstick_large`: see 1.15 pine_large (1.14 only).
|
|
* `dark_oak`
|
|
* `acacia`
|
|
* `oak_swamp`: oak with more leaves and vines.
|
|
* `well`: desert well
|
|
* `grass`: a few spots of tall grass
|
|
* `grass_jungle`: little bushier grass feature (1.14 only)
|
|
* `lush_grass`: grass with patchy ferns (1.15+)
|
|
* `tall_grass`: 2-high grass patch (1.15+)
|
|
* `fern`: a few random 2-high ferns
|
|
* `cactus`: random cacti
|
|
* `dead_bush`: a few random dead bushi
|
|
* `fossils`: underground fossils, placement little wonky
|
|
* `mushroom_brown`: large brown mushroom.
|
|
* `mushroom_red`: large red mushroom.
|
|
* `ice_spike`: ice spike. Require snow block below to place.
|
|
* `glowstone`: glowstone cluster. Required netherrack above it.
|
|
* `melon`: a patch of melons
|
|
* `melon_pile`: a pile of melons (1.15+)
|
|
* `pumpkin`: a patch of pumpkins
|
|
* `pumpkin_pile`: a pile of pumpkins (1.15+)
|
|
* `sugarcane`
|
|
* `lilypad`
|
|
* `dungeon`: Dungeon. These are hard to place, and fail often.
|
|
* `iceberg`: Iceberg. Generate at sea level.
|
|
* `iceberg_blue`: Blue ice iceberg.
|
|
* `lake`
|
|
* `lava_lake`
|
|
* `end_island`
|
|
* `chorus`: Chorus plant. Require endstone to place.
|
|
* `sea_grass`: a patch of sea grass. Require water.
|
|
* `sea_grass_river`: a variant.
|
|
* `kelp`
|
|
* `coral_tree, coral_mushroom, coral_claw`: various coral types, random color.
|
|
* `coral`: random coral structure. Require water to spawn.
|
|
* `sea_pickle`
|
|
* `boulder`: A rocky, mossy formation from a giant taiga biome. Doesn't update client properly, needs relogging.
|