# 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.