moved scarpet docs to markdown files
This commit is contained in:
gnembon committed
1 parent
c7603038da
commit
d93a0dbdf4
19 files changed
+3154
-2712
No files matched your search
@@ -0,0 +1,246 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Iterating over larger areas of blocks
|
||||
|
||||
These functions help scan larger areas of blocks without using generic loop functions, like nested `loop`.
|
||||
|
||||
### `scan(cx, cy, cz, dx, dy, dz, px?, py?, pz?, expr)`
|
||||
|
||||
Evaluates expression over area of blocks defined by its center (`cx, cy, cz`), expanded in all directions
|
||||
by `dx, dy, dz` blocks, or optionally in negative with `d` coords, and `p` coords in positive values. `expr`
|
||||
receives `_x, _y, _z` as coords of current analyzed block and `_`, which represents the block itself.
|
||||
|
||||
### `volume(x1, y1, z1, x2, y2, z2, expr)`
|
||||
|
||||
Evaluates expression for each block in the area, the same as the `scan`function, but using two opposite corners of
|
||||
the rectangular cuboid. Any corners can be specified, its like you would do with `/fill` command.
|
||||
|
||||
### `neighbours(x, y, z), neighbours(block), neighbours(l(x,y,z))`
|
||||
|
||||
Returns the list of 6 neighbouring blocks to the argument. Commonly used with other loop functions like `for`.
|
||||
|
||||
<pre>
|
||||
for(neighbours(x,y,z),air(_)) => 4 // number of air blocks around a block
|
||||
</pre>
|
||||
|
||||
### `rect(cx, cy, cz, dx?, dy?, dz?, px?, py?, pz?)`
|
||||
|
||||
returns an iterator, just like `range` function that iterates over rectangular cubarea of blocks. If only center
|
||||
point is specified, it iterates over 27 blocks. If `d` arguments are specified, expands selection of respective
|
||||
number of blocks in each direction. If `p` arguments are specified, it uses `d` for negative offset, and `p` for positive.
|
||||
|
||||
### `diamond(cx, cy, cz, radius?, height?)`
|
||||
|
||||
Iterates over a diamond like area of blocks. With no radius and height, its 7 blocks centered around the middle
|
||||
(block + neighbours). With a radius specified, it expands shape on x and z coords, and with a custom height, on y.
|
||||
Any of these can be zero as well. radius of 0 makes a stick, height of 0 makes a diamond shape pad.
|
||||
@@ -0,0 +1,530 @@
|
||||
# Blocks / World API
|
||||
|
||||
## Specifying blocks
|
||||
|
||||
### `block(x, y, z)`, `block(l(x,y,z))`, `block(state)`
|
||||
|
||||
Returns either a block from specified location, or block with a specific state (as used by `/setblock` command),
|
||||
so allowing for block properties, block entity data etc. Blocks otherwise can be referenced everywhere by its simple
|
||||
string name, but its only used in its default state.
|
||||
|
||||
<pre>
|
||||
block('air') => air
|
||||
block('iron_trapdoor[half=top]') => iron_trapdoor
|
||||
block(0,0,0) == block('bedrock') => 1
|
||||
block('hopper[facing=north]{Items:[{Slot:1b,id:"minecraft:slime_ball",Count:16b}]}') => hopper
|
||||
</pre>
|
||||
|
||||
Retrieving a block with `block` function has also a side-effect of evaluating its current state and data.
|
||||
So if you use it later it will reflect block state and data of the block that was when block was called, rather than
|
||||
when it was used. Block values passed in various places like `scan` functions, etc, are not fully evaluated unless
|
||||
its properties are needed. This means that if the block at the location changes before its queried in the program this
|
||||
might result in getting the later state, which might not be desired. Consider the following example:
|
||||
|
||||
<pre>set(10,10,10,'stone');
|
||||
scan(10,10,10,0,0,0, b = _);
|
||||
set(10,10,10,'air');
|
||||
print(b); // 'air', block was remembered 'lazily', and evaluated by `print`, when it was already set to air
|
||||
set(10,10,10,'stone');
|
||||
scan(10,10,10,0,0,0, b = block(_));
|
||||
set(10,10,10,'air');
|
||||
print(b); // 'stone', block was evaluated 'eagerly' but call to `block`
|
||||
</pre>
|
||||
|
||||
## World Manipulation
|
||||
|
||||
All the functions below can be used with block value, queried with coord triple, or 3-long list. All `pos` in the
|
||||
functions referenced below refer to either method of passing block position.
|
||||
|
||||
### `set(pos, block, property?, value?, ...)`
|
||||
|
||||
First part of the `set` function is either a coord triple, list of three numbers, or other block with coordinates.
|
||||
Second part, `block` is either block value as a result of `block()` function string value indicating the block name,
|
||||
and optional `property - value` pairs for extra block properties. If `block` is specified only by name, then if a
|
||||
destination block is the same the `set` operation is skipped, otherwise is executed, for other potential extra
|
||||
properties.
|
||||
|
||||
The returned value is either the block state that has been set, or `false` if block setting was skipped
|
||||
|
||||
<pre>
|
||||
set(0,5,0,'bedrock') => bedrock
|
||||
set(l(0,5,0), 'bedrock') => bedrock
|
||||
set(block(0,5,0), 'bedrock') => bedrock
|
||||
scan(0,5,0,0,0,0,set(_,'bedrock')) => 1
|
||||
set(pos(players()), 'bedrock') => bedrock
|
||||
set(0,0,0,'bedrock') => 0 // or 1 in overworlds generated in 1.8 and before
|
||||
scan(0,100,0,20,20,20,set(_,'glass'))
|
||||
// filling the area with glass
|
||||
scan(0,100,0,20,20,20,set(_,block('glass')))
|
||||
// little bit faster due to internal caching of block state selectors
|
||||
b = block('glass'); scan(0,100,0,20,20,20,set(_,b))
|
||||
// yet another option, skips all parsing
|
||||
set(x,y,z,'iron_trapdoor') // sets bottom iron trapdoor
|
||||
set(x,y,z,'iron_trapdoor[half=top]') // Incorrect. sets bottom iron trapdoor - no parsing of properties
|
||||
set(x,y,z,'iron_trapdoor','half','top') // correct - top trapdoor
|
||||
set(x,y,z, block('iron_trapdoor[half=top]')) // also correct, block() provides extra parsing
|
||||
set(x,y,z,'hopper[facing=north]{Items:[{Slot:1b,id:"minecraft:slime_ball",Count:16b}]}') // extra block data
|
||||
</pre>
|
||||
|
||||
### `without_updates(expr)`
|
||||
|
||||
Evaluates subexpression without causing updates when blocks change in the world
|
||||
|
||||
Consider following scenario: We would like to generate a bunch of terrain in a flat world following a perling noise
|
||||
generator. The following code causes cascading effect as blocks placed on chunk borders will cause other chunks to get
|
||||
loaded to full, thus generated:
|
||||
|
||||
<pre>
|
||||
__config() -> m(l('scope', 'global'));
|
||||
__on_chunk_generated(x, z) -> (
|
||||
scan(x,0,z,0,0,0,15,15,15,
|
||||
if (perlin(_x/16, _y/8, _z/16) > _y/16,
|
||||
set(_, 'black_stained_glass');
|
||||
)
|
||||
)
|
||||
)
|
||||
</pre>
|
||||
|
||||
The following addition resolves this issue, by not allowing block updates pass chunk borders:
|
||||
|
||||
<pre>
|
||||
__config() -> m(l('scope', 'global'));
|
||||
__on_chunk_generated(x, z) -> (
|
||||
without_updates(
|
||||
scan(x,0,z,0,0,0,15,15,15,
|
||||
if (perlin(_x/16, _y/8, _z/16) > _y/16,
|
||||
set(_, 'black_stained_glass');
|
||||
)
|
||||
)
|
||||
)
|
||||
)
|
||||
</pre>
|
||||
|
||||
### `place_item(item, pos, facing?, sneak?)`
|
||||
|
||||
Places a given item in the world like it was placed by a player. Item names are default minecraft item name,
|
||||
less the minecraft prefix. Default facing is 'up', but there are other options: 'down', 'north', 'east', 'south',
|
||||
'west', but also there are other secondary directions important for placement of blocks like stairs, doors, etc.
|
||||
Try experiment with options like 'north-up' which is placed facing north with cursor pointing to the upper part of the
|
||||
block, or 'up-north', which means a block placed facing up (player looking down) and placed smidge away of the block
|
||||
center towards north. Optional sneak is a boolean indicating if a player would be sneaking while placing the
|
||||
block - this option only affects placement of chests and scaffolding at the moment. Returns true if placement was
|
||||
successful, false otherwise.
|
||||
|
||||
<pre>
|
||||
place_item('stone',x,y,z) // places a stone block on x,y,z block
|
||||
place_item('piston,x,y,z,'down') // places a piston facing down
|
||||
place_item('carrot',x,y,z) // attempts to plant a carrot plant. Returns true if could place carrots at that position.
|
||||
</pre>
|
||||
|
||||
### `set_poi(pos, type, occupancy?)`
|
||||
|
||||
Sets a Point of Interest (POI) of a specified type with optional custom occupancy. By default new POIs are not occupied.
|
||||
If type is `null`, POI at position is removed. In any case, previous POI is also removed. Available POI types are:
|
||||
|
||||
* `'unemployed', 'armorer', 'butcher', 'cartographer', 'cleric', 'farmer', 'fisherman', 'fletcher', 'leatherworker', 'librarian', 'mason', 'nitwit', 'shepherd', 'toolsmith', 'weaponsmith', 'home', 'meeting', 'beehive', 'bee_nest', 'nether_portal'`
|
||||
|
||||
Interestingly, `unemployed`, and `nitwit` are not used in the game, meaning, they could be used as permanent spatial
|
||||
markers for scarpet apps. `meeting` is the only one with increased max occupancy of 32.
|
||||
|
||||
### `set_biome(pos, biome_name)`
|
||||
|
||||
changes biome at that block position.
|
||||
|
||||
### `update(pos)`
|
||||
|
||||
Causes a block update at position.
|
||||
|
||||
### `block_tick(pos)`
|
||||
|
||||
Causes a block to tick at position.
|
||||
|
||||
### `random_tick(pos)`
|
||||
|
||||
Causes a random tick at position.
|
||||
|
||||
### `destroy(pos), destroy(pos, -1), destroy(pos, <N>), destroy(pos, tool, nbt?)`
|
||||
|
||||
Destroys the block like it was mined by a player. Add -1 for silk touch, and positive number for fortune level.
|
||||
If tool is specified, and optionally its nbt, it will use that tool and will attempt to mine the block with this tool.
|
||||
If called without item context, this function, unlike harvest, will affect all kinds of blocks. If called with item
|
||||
in context, it will fail to break blocks that cannot be broken by a survival player.
|
||||
|
||||
Without item context it returns `false` if failed to destroy the block and `true` if block breaking was successful.
|
||||
In item context, `true` means that breaking item has no nbt to use, `null` indicating that the tool should be
|
||||
considered broken in process, and `nbt` type value, for a resulting NBT tag on a hypothetical tool. Its up to the
|
||||
programmer to use that nbt to apply it where it belong
|
||||
|
||||
Here is a sample code that can be used to mine blocks using items in player inventory, without using player context
|
||||
for mining. Obviously, in this case the use of `harvest` would be much more applicable:
|
||||
|
||||
<pre>
|
||||
mine(x,y,z) ->
|
||||
(
|
||||
p = player();
|
||||
slot = p~'selected_slot';
|
||||
item_tuple = inventory_get(p, slot);
|
||||
if (!item_tuple, destroy(x,y,z,'air'); return()); // empty hand, just break with 'air'
|
||||
l(item, count, tag) = item_tuple;
|
||||
tag_back = destroy(x,y,z, item, tag);
|
||||
if (tag_back == false, // failed to break the item
|
||||
return(tag_back)
|
||||
);
|
||||
if (tag_back == true, // block broke, tool has no tag
|
||||
return(tag_back)
|
||||
);
|
||||
if (tag_back == null, //item broke
|
||||
delete(tag:'Damage');
|
||||
inventory_set(p, slot, count-1, item, tag);
|
||||
return(tag_back)
|
||||
);
|
||||
if (type(tag_back) == 'nbt', // item didn't break, here is the effective nbt
|
||||
inventory_set(p, slot, count, item, tag_back);
|
||||
return(tag_back)
|
||||
);
|
||||
print('How did we get here?');
|
||||
)
|
||||
</pre>
|
||||
|
||||
### `harvest(player, pos)`
|
||||
|
||||
Causes a block to be harvested by a specified player entity. Honors player item enchantments, as well as damages the
|
||||
tool if applicable. If the entity is not a valid player, no block gets destroyed. If a player is not allowed to break
|
||||
that block, a block doesn't get destroyed either.
|
||||
|
||||
## Block and World querying
|
||||
|
||||
### `pos(block), pos(entity)`
|
||||
|
||||
Returns a triple of coordinates of a specified block or entity. Technically entities are queried with `query` function
|
||||
and the same can be achieved with `query(entity,'pos')`, but for simplicity `pos` allows to pass all positional objects.
|
||||
|
||||
<pre>
|
||||
pos(block(0,5,0)) => l(0,5,0)
|
||||
pos(players()) => l(12.3, 45.6, 32.05)
|
||||
pos(block('stone')) => Error: Cannot fetch position of an unrealized block
|
||||
</pre>
|
||||
|
||||
### `pos_offset(pos, direction, amount?)`
|
||||
|
||||
Returns a coords triple that is offset in a specified `direction` by `amount` of blocks. The default offset amount is
|
||||
1 block. To offset into opposite facing, use negative numbers for the `amount`.
|
||||
|
||||
<pre>
|
||||
pos_offset(block(0,5,0), 'up', 2) => l(0,7,0)
|
||||
pos_offset(l(0,5,0), 'up', -2 ) => l(0,3,0)
|
||||
</pre>
|
||||
|
||||
### `block_properties(pos)`
|
||||
|
||||
Returns a list of available block properties for a particular block. If a block has no properties, returns an empty list.
|
||||
|
||||
### `property(pos, name)`
|
||||
|
||||
Returns property of block at `pos`, or specified by `block` argument. If a block doesn't have that property, `null`
|
||||
value is returned. Returned values are always strings. It is expected from the user to know what to expect and convert
|
||||
values to numbers using `number()` function or booleans using `bool()` function.
|
||||
|
||||
<pre>
|
||||
set(x,y,z,'iron_trapdoor','half','top'); property(x,y,z,'half') => top
|
||||
set(x,y,z,'air'); property(x,y,z,'half') => null
|
||||
property(block('iron_trapdoor[half=top]'),'half') => top
|
||||
property(block('iron_trapdoor[half=top]'),'powered') => false
|
||||
bool(property(block('iron_trapdoor[half=top]'),'powered')) => 0
|
||||
</pre>
|
||||
|
||||
### `block_data(pos)`
|
||||
|
||||
Return NBT string associated with specific location, or null if the block does not carry block data. Can be currently
|
||||
used to match specific information from it, or use it to copy to another block
|
||||
|
||||
<pre> block_data(x,y,z) => '{TransferCooldown:0,x:450,y:68, ... }'
|
||||
</pre>
|
||||
|
||||
### `poi(pos), poi(pos, radius), poi(pos, radius, status)`
|
||||
|
||||
Queries a POI (Point of Interest) at a given position, returning `null` if none is found, or tuple of poi type and its
|
||||
occupancy load. With optional `radius` and `status`, returns a list of POIs around `pos` within a given `radius`.
|
||||
If `status` is specified (either 'available', or 'occupied') returns only POIs with that status. The return format is
|
||||
again, poi type, occupancy load, and extra tripple of coordinates.
|
||||
|
||||
Querying for POIs using the radius is intended use of POI mechanics and ability of accessing individual POIs
|
||||
via `poi(pos)` in only provided for completness.
|
||||
|
||||
<pre>
|
||||
poi(x,y,z) => null // nothing set at position
|
||||
poi(x,y,z) => ['meeting',3] // its a bell-type meeting point occupied by 3 villagers
|
||||
poi(x,y,z,5) => [] // nothing around
|
||||
poi(x,y,z,5) => [['nether_portal',0,[7,8,9]],['nether_portal',0,[7,9,9]]] // two portal blocks in the range
|
||||
</pre>
|
||||
|
||||
### `biome(pos)`
|
||||
|
||||
returns biome at that block position.
|
||||
|
||||
### `solid(pos)`
|
||||
|
||||
Boolean function, true if the block is solid
|
||||
|
||||
### `air(pos)`
|
||||
|
||||
Boolean function, true if a block is air.... or cave air... or void air.... or any other air they come up with.
|
||||
|
||||
### `liquid(pos)`
|
||||
|
||||
Boolean function, true if the block is liquid, or liquidlogged
|
||||
|
||||
### `flammable(pos)`
|
||||
|
||||
Boolean function, true if the block is flammable
|
||||
|
||||
### `transparent(pos)`
|
||||
|
||||
Boolean function, true if the block is transparent
|
||||
|
||||
### `opacity(pos)`
|
||||
|
||||
Numeric, returning opacity level of a block
|
||||
|
||||
### `blocks_daylight(pos)`
|
||||
|
||||
Boolean function, true if the block blocks daylight
|
||||
|
||||
### `emitted_light(pos)`
|
||||
|
||||
Numeric, returning light level emitted from block
|
||||
|
||||
### `light(pos)`
|
||||
|
||||
Integer function, returning total light level at position
|
||||
|
||||
### `block_light(pos)`
|
||||
|
||||
Integer function, returning block light at position. From torches and other light sources.
|
||||
|
||||
### `sky_light(pos)`
|
||||
|
||||
Numeric function, returning sky light at position. From the sky access.
|
||||
|
||||
### `see_sky(pos)`
|
||||
|
||||
Boolean function, returning true if the block can see sky.
|
||||
|
||||
### `hardness(pos)`
|
||||
|
||||
Numeric function, indicating hardness of a block.
|
||||
|
||||
### `blast_resistance(pos)`
|
||||
|
||||
Numeric function, indicating blast_resistance of a block.
|
||||
|
||||
### `in_slime_chunk(pos)`
|
||||
|
||||
Boolean indicating if the given block position is in a slime chunk.
|
||||
|
||||
### `top(type, pos)`
|
||||
|
||||
Returns the Y value of the topmost block at given x, z coords (y value of a block is not important), according to the
|
||||
heightmap specified by `type`. Valid options are:
|
||||
|
||||
* `light`: topmost light blocking block (1.13 only)
|
||||
* `motion`: topmost motion blocking block
|
||||
* `terrain`: topmost motion blocking block except leaves
|
||||
* `ocean_floor`: topmost non-water block
|
||||
* `surface`: topmost surface block
|
||||
|
||||
<pre>
|
||||
top('motion', x, y, z) => 63
|
||||
top('ocean_floor', x, y, z) => 41
|
||||
</pre>
|
||||
|
||||
### `loaded(pos)`
|
||||
|
||||
Boolean function, true if the block is accessible for the game mechanics. Normally `scarpet` doesn't check if operates
|
||||
on loaded area - the game will automatically load missing blocks. We see this as advantage. Vanilla `fill/clone`
|
||||
commands only check the specified corners for loadness.
|
||||
|
||||
To check if block is truly loaded, I mean in memory, use `generation_status(x) != null`, as chunks can still be loaded
|
||||
outside of the playable area, just are not used any of the game mechanics processes.
|
||||
|
||||
<pre>
|
||||
loaded(pos(players())) => 1
|
||||
loaded(100000,100,1000000) => 0
|
||||
</pre>
|
||||
|
||||
### `(Deprecated) loaded_ep(pos)`
|
||||
|
||||
Boolean function, true if the block is loaded and entity processing, as per 1.13.2
|
||||
|
||||
Deprecated as of scarpet 1.6, use `loaded_status(x) > 0`, or just `loaded(x)` with the same effect
|
||||
|
||||
### `loaded_status(pos)`
|
||||
|
||||
Returns loaded status as per new 1.14 chunk ticket system, 0 for inaccessible, 1 for border chunk, 2 for ticking,
|
||||
3 for entity ticking
|
||||
|
||||
### `generation_status(pos), generation_status(pos, true)`
|
||||
|
||||
Returns generation status as per new 1.14 chunk ticket system. Can return any value from several available but chunks
|
||||
can only be valid in a few states: `full`, `features`, `liquid_carvers`, and `structure_starts`. Returns `null`
|
||||
if the chunk is not in memory unless called with optional `true`.
|
||||
|
||||
### `structures(pos), structures(pos, structure_name)`
|
||||
|
||||
Returns structure information for a given block position. Note that structure information is the same for all the
|
||||
blocks from the same chunk. `structures` function can be called with a block, or a block and a structure name. In
|
||||
the first case it returns a map of structures at a given position, keyed by structure name, with values indicating
|
||||
the bounding box of the structure - a pair of two 3-value coords (see examples). When called with an extra structure
|
||||
name, returns list of components for that structure, with their name, direction and two sets of coordinates
|
||||
indicating the bounding box of the structure piece.
|
||||
|
||||
### `structure_references(pos), structure_references(pos, structure_name)`
|
||||
|
||||
Returns structure information that a chunk with a given block position is part of. `structure_references` function
|
||||
can be called with a block, or a block and a structure name. In the first case it returns a list of structure names
|
||||
that give chunk belongs to. When called with an extra structure name, returns list of positions pointing to the
|
||||
lowest block position in chunks that hold structure starts for these structures. You can query that chunk structures
|
||||
then to get its bounding boxes.
|
||||
|
||||
### `set_structure(pos, structure_name), set_structure(pos, structure_name, null)`
|
||||
|
||||
Creates or removes structure information of a structure associated with a chunk of `pos`. Unlike `plop`, blocks are
|
||||
not placed in the world, only structure information is set. For the game this is a fully functional structure even
|
||||
if blocks are not set. To remove structure a given point is in, use `structure_references` to find where current
|
||||
structure starts.
|
||||
|
||||
### `suffocates(pos)`
|
||||
|
||||
Boolean function, true if the block causes suffocation.
|
||||
|
||||
### `power(pos)`
|
||||
|
||||
Numeric function, returning redstone power level at position.
|
||||
|
||||
### `ticks_randomly(pos)`
|
||||
|
||||
Boolean function, true if the block ticks randomly.
|
||||
|
||||
### `blocks_movement(pos)`
|
||||
|
||||
Boolean function, true if block at position blocks movement.
|
||||
|
||||
### `block_sound(pos)`
|
||||
|
||||
Returns the name of sound type made by the block at position. One of:
|
||||
|
||||
* `wood`
|
||||
* `gravel`
|
||||
* `grass`
|
||||
* `stone`
|
||||
* `metal`
|
||||
* `glass`
|
||||
* `wool`
|
||||
* `sand`
|
||||
* `snow`
|
||||
* `ladder`
|
||||
* `anvil`
|
||||
* `slime`
|
||||
* `sea_grass`
|
||||
* `coral`
|
||||
|
||||
### `material(pos)`
|
||||
|
||||
Returns the name of material of the block at position. very useful to target a group of blocks. One of:
|
||||
|
||||
* `air`
|
||||
* `void`
|
||||
* `portal`
|
||||
* `carpet`
|
||||
* `plant`
|
||||
* `water_plant`
|
||||
* `vine`
|
||||
* `sea_grass`
|
||||
* `water`
|
||||
* `bubble_column`
|
||||
* `lava`
|
||||
* `snow_layer`
|
||||
* `fire`
|
||||
* `redstone_bits`
|
||||
* `cobweb`
|
||||
* `redstone_lamp`
|
||||
* `clay`
|
||||
* `dirt`
|
||||
* `grass`
|
||||
* `packed_ice`
|
||||
* `sand`
|
||||
* `sponge`
|
||||
* `wood`
|
||||
* `wool`
|
||||
* `tnt`
|
||||
* `leaves`
|
||||
* `glass`
|
||||
* `ice`
|
||||
* `cactus`
|
||||
* `stone`
|
||||
* `iron`
|
||||
* `snow`
|
||||
* `anvil`
|
||||
* `barrier`
|
||||
* `piston`
|
||||
* `coral`
|
||||
* `gourd`
|
||||
* `dragon_egg`
|
||||
* `cake`
|
||||
|
||||
### `map_colour(pos)`
|
||||
|
||||
Returns the map colour of a block at position. One of:
|
||||
|
||||
* `air`
|
||||
* `grass`
|
||||
* `sand`
|
||||
* `wool`
|
||||
* `tnt`
|
||||
* `ice`
|
||||
* `iron`
|
||||
* `foliage`
|
||||
* `snow`
|
||||
* `clay`
|
||||
* `dirt`
|
||||
* `stone`
|
||||
* `water`
|
||||
* `wood`
|
||||
* `quartz`
|
||||
* `adobe`
|
||||
* `magenta`
|
||||
* `light_blue`
|
||||
* `yellow`
|
||||
* `lime`
|
||||
* `pink`
|
||||
* `gray`
|
||||
* `light_gray`
|
||||
* `cyan`
|
||||
* `purple`
|
||||
* `blue`
|
||||
* `brown`
|
||||
* `green`
|
||||
* `red`
|
||||
* `black`
|
||||
* `gold`
|
||||
* `diamond`
|
||||
* `lapis`
|
||||
* `emerald`
|
||||
* `obsidian`
|
||||
* `netherrack`
|
||||
* `white_terracotta`
|
||||
* `orange_terracotta`
|
||||
* `magenta_terracotta`
|
||||
* `light_blue_terracotta`
|
||||
* `yellow_terracotta`
|
||||
* `lime_terracotta`
|
||||
* `pink_terracotta`
|
||||
* `gray_terracotta`
|
||||
* `light_gray_terracotta`
|
||||
* `cyan_terracotta`
|
||||
* `purple_terracotta`
|
||||
* `blue_terracotta`
|
||||
* `brown_terracotta`
|
||||
* `green_terracotta`
|
||||
* `red_terracotta`
|
||||
* `black_terracotta`
|
||||
@@ -0,0 +1,471 @@
|
||||
# Entity API
|
||||
|
||||
## Entity Selection
|
||||
|
||||
Entities have to be fetched before using them. Entities can also change their state between calls to the script if
|
||||
game happens either in between separate calls to the programs, or if the program calls `game_tick` on its own.
|
||||
In this case - entities would need to be re-fetched, or the code should account for entities getting dead.
|
||||
|
||||
### `player(), player(type), player(name)`
|
||||
|
||||
With no arguments, it returns the calling player or the player closest to the caller. Note that the main context
|
||||
will receive `p` variable pointing to this player. With `type` or `name` specified it will try first to match a type,
|
||||
returning a list of players matching a type, and if this fails, will assume its player name query retuning player with
|
||||
that name, or `null` if no player was found. With `'all'`, list of all players in the game, in all dimensions, so end
|
||||
user needs to be cautious, that you might be referring to wrong blocks and entities around the player in question.
|
||||
With `type = '*'` it returns all players in caller dimension, `'survival'` returns all survival and adventure players,
|
||||
`'creative'` returns all creative players, `'spectating'` returns all spectating players, and `'!spectating'`,
|
||||
all not-spectating players. If all fails, with `name`, the player in question, if is logged in.
|
||||
|
||||
### `entity_id(uuid), entity_id(id)`
|
||||
|
||||
Fetching entities wither by their ID obtained via `entity ~ 'id'`, which is unique for a dimension and current world
|
||||
run, or by UUID, obtained via `entity ~ 'uuid'`. It returns null if no such entity is found. Safer way to 'store'
|
||||
entities between calls, as missing entities will be returning `null`. Both calls using UUID or numerical ID are `O(1)`,
|
||||
but obviously using UUIDs takes more memory and compute.
|
||||
|
||||
### `entity_list(type)`
|
||||
|
||||
Returns global lists of entities in the current dimension of a specified type. Currently the following
|
||||
selectors are available:
|
||||
|
||||
* `*`: all entites
|
||||
* `living`
|
||||
* `items`
|
||||
* `players`
|
||||
* `!players`
|
||||
|
||||
### `entity_area(type, cx, cy, cz, dx, dy, dz)`
|
||||
|
||||
Returns entities of a specified type in an area centered on `cx, cy, cz` and at most `dx, dy, dz` blocks away from
|
||||
the center point. Uses same selectors as `entities_list`
|
||||
|
||||
### `entity_selector(selector)`
|
||||
|
||||
Returns entities satisfying given vanilla entity selector. Most complex among all the methods of selecting entities,
|
||||
but the most capable. Selectors are cached so should be as fast as other methods of selecting entities.
|
||||
|
||||
### `spawn(name, pos, nbt?)`
|
||||
|
||||
Spawns and places an entity in world, like `/summon` vanilla command. Requires a position to spawn, and optional
|
||||
extra nbt data to merge with the entity. What makes it different from calling `run('summon ...')`, is the fact that
|
||||
you get the entity back as a return value, which is swell.
|
||||
|
||||
## Entity Manipulation
|
||||
|
||||
Unlike with blocks, that use plethora of vastly different querying functions, entities are queried with `query`
|
||||
function and altered via `modify` function. Type of information needed or values to be modified are different for
|
||||
each call.
|
||||
|
||||
Using `~` (in) operator is an alias for `query`. Especially useful if a statement has no arguments,
|
||||
which in this case can be radically simplified
|
||||
|
||||
<pre>
|
||||
query(p, 'name') <=> p ~ 'name' // much shorter and cleaner
|
||||
query(p, 'holds', 'offhand') <=> p ~ l('holds', 'offhand') // not really but can be done
|
||||
</pre>
|
||||
|
||||
### `query(e,'removed')`
|
||||
|
||||
Boolean. True if the entity is removed
|
||||
|
||||
### `query(e,'id')`
|
||||
|
||||
Returns numerical id of the entity. Most efficient way to keep track of entites in a script.
|
||||
Ids are only unique within current game session (ids are not preserved between restarts),
|
||||
and dimension (each dimension has its own ids which can overlap.
|
||||
|
||||
### `query(e,'uuid')`
|
||||
|
||||
Returns UUID (unique id) of the entity. Can be used to access entities with the other vanilla commands and
|
||||
remains unique regardless of the dimension, and is preserved between game restarts. Apparently players cannot be
|
||||
accessed via UUID, but name instead.
|
||||
|
||||
<pre>
|
||||
map(entities_area('*',x,y,z,30,30,30),run('kill '+query(_,'id'))) // doesn't kill the player
|
||||
</pre>
|
||||
|
||||
### `query(e,'pos')`
|
||||
|
||||
Triple of entity position
|
||||
|
||||
### `query(e,'location')`
|
||||
|
||||
Quin-tuple of entity position (x, y, and z coords), and rotation (yaw, pitch)
|
||||
|
||||
### `query(e,'x'), query(e,'y'), query(e,'z')`
|
||||
|
||||
Respective entity coordinate
|
||||
|
||||
### `query(e,'pitch'), query(e,'yaw')`
|
||||
|
||||
Pitch and Yaw or where entity is looking.
|
||||
|
||||
### `query(e,'look')`
|
||||
|
||||
Returns a 3d vector where the entity is looking.
|
||||
|
||||
### `query(e,'motion')`
|
||||
|
||||
Triple of entity motion vector, `l(motion_x, motion_y, motion_z)`
|
||||
|
||||
### `query(e,'motion_x'), query(e,'motion_y'), query(e,'motion_z')`
|
||||
|
||||
Respective component of the motion vector
|
||||
|
||||
### `query(e,'name'), query(e,'custom_name'), query(e,'type')`
|
||||
|
||||
String of entity name
|
||||
|
||||
<pre>query(e,'name') => Leatherworker
|
||||
query(e,'custom_name') => null
|
||||
query(e,'type') => villager
|
||||
</pre>
|
||||
|
||||
### `query(e,'is_riding')`
|
||||
|
||||
Boolean. True if riding another entity.
|
||||
|
||||
### `query(e,'is_ridden')`
|
||||
|
||||
Boolean. True if another entity is riding it.
|
||||
|
||||
### `query(e,'passengers')`
|
||||
|
||||
List of entities riding the entity.
|
||||
|
||||
### `query(e,'mount')`
|
||||
|
||||
Entity that `e` rides.
|
||||
|
||||
### `query(e,'tags')`
|
||||
|
||||
List of entity tags.
|
||||
|
||||
### `query(e,'has_tags',tag)`
|
||||
|
||||
Boolean, True if the entity is marked with `tag`.
|
||||
|
||||
### `query(e,'is_burning')`
|
||||
|
||||
Boolean, True if the entity is burning.
|
||||
|
||||
### `query(e,'fire')`
|
||||
|
||||
Number of remaining ticks of being on fire.
|
||||
|
||||
### `query(e,'silent')`
|
||||
|
||||
Boolean, True if the entity is silent.
|
||||
|
||||
### `query(e,'gravity')`
|
||||
|
||||
Boolean, True if the entity is affected by gravity, like most entities do.
|
||||
|
||||
### `query(e,'immune_to_fire')`
|
||||
|
||||
Boolean, True if the entity is immune to fire.
|
||||
|
||||
### `query(e,'dimension')`
|
||||
|
||||
Name of the dimension entity is in.
|
||||
|
||||
### `query(e,'height')`
|
||||
|
||||
Height of the entity.
|
||||
|
||||
### `query(e,'width')`
|
||||
|
||||
Width of the entity.
|
||||
|
||||
### `query(e,'eye_height')`
|
||||
|
||||
Eye height of the entity.
|
||||
|
||||
### `query(e,'age')`
|
||||
|
||||
Age, in ticks, of the entity, i.e. how long it existed.
|
||||
|
||||
### `query(e,'breeding_age')`
|
||||
|
||||
Breeding age of passive entity, in ticks. If negative it it time to adulthood, if positive, breeding cooldown
|
||||
|
||||
### `query(e,'despawn_timer')`
|
||||
|
||||
For living entities - the number of ticks they fall outside of immediate player presence.
|
||||
|
||||
### `query(e,'item')`
|
||||
|
||||
The item triple (name, count, nbt) if its an item entity, `null` otherwise
|
||||
|
||||
### `query(e,'count')`
|
||||
|
||||
Number of items in a stack from item entity, `null` otherwise
|
||||
|
||||
### `query(e,'pickup_delay')`
|
||||
|
||||
Retrieves pickup delay timeout for an item entity, `null` otherwise
|
||||
|
||||
### `query(e,'is_baby')`
|
||||
|
||||
Boolean, true if its a baby.
|
||||
|
||||
### `query(e,'target')`
|
||||
|
||||
Returns mob's attack target or null if none or not applicable.
|
||||
|
||||
### `query(e,'home')`
|
||||
|
||||
Returns creature's home position or null if none or not applicable.
|
||||
|
||||
### `query(e,'sneaking')`
|
||||
|
||||
Boolean, true if entity is sneaking.
|
||||
|
||||
### `query(e,'sprinting')`
|
||||
|
||||
Boolean, true if entity is sprinting.
|
||||
|
||||
### `query(e,'swimming')`
|
||||
|
||||
Boolean, true if entity is swimming.
|
||||
|
||||
### `query(e,'jumping')`
|
||||
|
||||
Boolean, true if entity is jumping.
|
||||
|
||||
### `query(e,'gamemode')`
|
||||
|
||||
String with gamemode, or `null` if not a player.
|
||||
|
||||
### `query(e,'gamemode_id')`
|
||||
|
||||
Good'ol gamemode id, or null if not a player.
|
||||
|
||||
### `query(e,'player_type')`
|
||||
|
||||
Returns `null` if the argument is not a player, otherwise:
|
||||
|
||||
* `singleplayer`: for singleplayer game
|
||||
* `multiplayer`: for players on a dedicated server
|
||||
* `lan_host`: for singleplayer owner that opened the game to LAN
|
||||
* `lan_player`: for all other players that connected to a LAN host
|
||||
* `fake`: any carpet-spanwed fake player
|
||||
* `shadow`: any carpet-shadowed real player
|
||||
* `realms`: ?
|
||||
|
||||
### `query(e,'permission_level')`
|
||||
|
||||
Player's permission level, or `null` if not applicable for this entity.
|
||||
|
||||
### `query(e,'effect',name?)`
|
||||
|
||||
Without extra arguments, it returns list of effect active on a living entity. Each entry is a triple of short
|
||||
effect name, amplifier, and remaining duration. With an argument, if the living entity has not that potion active,
|
||||
returns `null`, otherwise return a tuple of amplifier and remaining duration.
|
||||
|
||||
<pre>
|
||||
query(p,'effect') => [[haste, 0, 177], [speed, 0, 177]]
|
||||
query(p,'effect','haste') => [0, 177]
|
||||
query(p,'effect','resistance') => null
|
||||
</pre>
|
||||
|
||||
### `query(e,'health')`
|
||||
|
||||
Number indicating remaining entity health, or `null` if not applicable.
|
||||
|
||||
### `query(e,'holds',slot?)`
|
||||
|
||||
Returns triple of short name, stack count, and NBT of item held in `slot`. Available options for `slot` are:
|
||||
|
||||
* `mainhand`
|
||||
* `offhand`
|
||||
* `head`
|
||||
* `chest`
|
||||
* `legs`
|
||||
* `feet`
|
||||
|
||||
If `slot` is not specified, it defaults to the main hand.
|
||||
|
||||
### `query(e,'selected_slot')`
|
||||
|
||||
Number indicating the selected slot of entity inventory. Currently only applicable to players.
|
||||
|
||||
### `query(e,'facing', order?)`
|
||||
|
||||
Returns where the entity is facing. optional order (number from 0 to 5, and negative), indicating primary directions
|
||||
where entity is looking at. From most prominent (order 0) to opposite (order 5, or -1)
|
||||
|
||||
### `query(e,'trace', reach?, options?...)`
|
||||
|
||||
Returns the result of ray tracing from entity perspective, indicating what it is looking at. Default reach is 4.5
|
||||
blocks (5 for creative players), and by default it traces for blocks and entities, identical to player attack tracing
|
||||
action. This can be customized with `options`, use 'blocks' to trace for blocks, 'liquids' to include liquid blocks
|
||||
as possible results, and 'entities' to trace entities. Any combination of the above is possible. When tracing
|
||||
entities and blocks, blocks will take over the priority even if transparent or non-colliding
|
||||
(aka fighting chickens in tall grass).
|
||||
|
||||
Regardless of the options selected, the result could be `null` if nothing is in reach, entity, if look targets an
|
||||
entity, and block value if block is in reach.
|
||||
|
||||
### `query(e,'nbt',path?)`
|
||||
|
||||
Returns full NBT of the entity. If path is specified, it fetches only that portion of the NBT, that corresponds to the
|
||||
path. For specification of `path` attribute, consult vanilla `/data get entity` command.
|
||||
|
||||
Note that calls to `nbt` are considerably more expensive comparing to other calls in Minecraft API, and should only
|
||||
be used when there is no other option. Returned value is of type `nbt`, which can be further manipulated with nbt
|
||||
type objects via `get, put, has, delete`, so try to use API calls first for that.
|
||||
|
||||
## Entity Modification
|
||||
|
||||
Like with entity querying, entity modifications happen through one function. Most position and movements modifications
|
||||
don't work currently on players as their position is controlled by clients.
|
||||
|
||||
Currently there is no ability to modify NBT directly, but you could always use `run('data modify entity`
|
||||
|
||||
### `modify(e,'remove')`
|
||||
|
||||
Removes (not kills) entity from the game.
|
||||
|
||||
### `modify(e,'kill')`
|
||||
|
||||
Kills the entity.
|
||||
|
||||
### `modify(e, 'pos', x, y, z), modify(e, 'pos', l(x,y,z) )`
|
||||
|
||||
Moves the entity to a specified coords.
|
||||
|
||||
### `modify(e, 'location', x, y, z, yaw, pitch), modify(e, 'location', l(x, y, z, yaw, pitch) )`
|
||||
|
||||
Changes full location vector all at once.
|
||||
|
||||
### `modify(e, 'x', x), modify(e, 'y', y), modify(e, 'z', z)`
|
||||
|
||||
Moves the entity in.... one direction.
|
||||
|
||||
### `modify(e, 'pitch', pitch), modify(e, 'yaw', yaw)`
|
||||
|
||||
Changes entity's pitch or yaw.
|
||||
|
||||
### `modify(e, 'move', x, y, z), modify(e, 'move', l(x,y,z) )`
|
||||
|
||||
Moves the entity by a vector from its current location.
|
||||
|
||||
### `modify(e, 'motion', x, y, z), modify(e, 'motion', l(x,y,z) )`
|
||||
|
||||
Sets the motion vector (where and how much entity is moving).
|
||||
|
||||
### `modify(e, 'motion_z', x), modify(e, 'motion_y', y), modify(e, 'motion_z', z)`
|
||||
|
||||
Sets the corresponding component of the motion vector.
|
||||
|
||||
### `modify(e, 'accelerate', x, y, z), modify(e, 'accelerate', l(x, y, z) )`
|
||||
|
||||
Adds a vector to the motion vector. Most realistic way to apply a force to an entity.
|
||||
|
||||
### `modify(e, 'custom_name'), modify(e, 'custom_name', name )`
|
||||
|
||||
### `modify(e, 'age', number)`
|
||||
|
||||
Modifies entity's internal age counter. Fiddling with this will affect directly behaviours of complex
|
||||
entities, so use it with caution.
|
||||
|
||||
### `modify(e, 'pickup_delay', number)`
|
||||
|
||||
### `modify(e, 'breeding_age', number)`
|
||||
|
||||
### `modify(e, 'despawn_timer', number)`
|
||||
|
||||
Sets a custom despawn timer value.
|
||||
|
||||
### `modify(e, 'dismount')`
|
||||
|
||||
Dismounts riding entity.
|
||||
|
||||
### `modify(e, 'mount', other)`
|
||||
|
||||
Mounts the entity to the `other`.
|
||||
|
||||
### `modify(e, 'drop_passengers')`
|
||||
|
||||
Shakes off all passengers.
|
||||
|
||||
### `modify(e, 'mount_passengers', passenger, ? ...), modify(e, 'mount_passengers', l(passengers) )`
|
||||
|
||||
Mounts on all listed entities on `e`.
|
||||
|
||||
### `modify(e, 'tag', tag, ? ...), modify(e, 'tag', l(tags) )`
|
||||
|
||||
Adds tag / tags to the entity.
|
||||
|
||||
### `modify(e, 'clear_tag', tag, ? ...), modify(e, 'clear_tag', l(tags) )`
|
||||
|
||||
Removes tag from entity.
|
||||
|
||||
### `modify(e, 'talk')`
|
||||
|
||||
Make noises.
|
||||
|
||||
### `modify(e, 'ai', boolean)`
|
||||
|
||||
If called with `false` value, it will disable AI in the mob. `true` will enable it again.
|
||||
|
||||
### `modify(e, 'no_clip', boolean)`
|
||||
|
||||
Sets if the entity obeys any collisions, including collisions with the terrain and basic physics. Not affecting
|
||||
players, since they are controlled client side
|
||||
|
||||
### `modify(e, 'effect', name, duration?, amplifier?, show_particles?, show_icon?)`
|
||||
|
||||
Applies status effect to the living entity. Takes several optional parameters, which default to `0`, `true`
|
||||
and `true`. If no duration is specified, or it is null or 0, the effect is removed.
|
||||
|
||||
### `modify(e, 'home', null), modify(e, 'home', block, distance?), modify(e, 'home', x, y, z, distance?)`
|
||||
|
||||
Sets AI to stay around the home position, within `distance` blocks from it. `distance` defaults to 16 blocks.
|
||||
`null` removes it. _May_ not work fully with mobs that have this AI built in, like Villagers.
|
||||
|
||||
## Entity Events
|
||||
|
||||
There is a number of events that happen to entities that you can attach your own code to in the form of event handlers.
|
||||
The event handler is any function that runs in your package that accepts certain expected parameters, which you can
|
||||
expand with your own arguments. When it comes to the moment when the given command needs to be executed, it does so
|
||||
providing that number of arguments it accepts is equal number of event arguments, and extra arguments passed when
|
||||
defining the callback with `entity_event`
|
||||
|
||||
The following events can be handled by entities.
|
||||
|
||||
* `'on_tick'`: executes every tick right before entity is ticked in the game. Required arguments: `entity`
|
||||
* `'on_death'`: executes once when a living entity dies. Required arguments: `entity, reason`
|
||||
* `'on_removed'`: execute once when an entity is removed. Required arguments: `entity`
|
||||
* `'on_damaged'`: executed every time a living entity is about to receive damage.
|
||||
Required arguments: `entity, amount, source, attacking_entity`
|
||||
|
||||
It doesn't mean that all entity types will have a chance to execute a given event, but entities will not error
|
||||
when you will attach inapplicable event to it.
|
||||
|
||||
### `entity_event(e, event, call_name, args...)`
|
||||
|
||||
Attaches specific function from the current package to be called upon the `event`, with extra `args` curried to the
|
||||
original required arguments for the event handler
|
||||
|
||||
<pre>
|
||||
protect_villager(entity, amount, source, source_entity, healing_player) ->
|
||||
(
|
||||
if(source_entity && source_entity~'type' != 'player',
|
||||
modify(entity, 'health', amount + entity~'health' );
|
||||
particle('end_rod', pos(entity)+l(0,3,0));
|
||||
print(str('%s healed thanks to %s', entity, healing_player))
|
||||
)
|
||||
);
|
||||
__on_player_interacts_with_entity(player, entity, hand) ->
|
||||
(
|
||||
if (entity~'type' == 'villager',
|
||||
entity_event(entity, 'on_damage', 'protect_villager', player~'name')
|
||||
)
|
||||
)
|
||||
</pre>
|
||||
|
||||
In this case this will protect a villager from entity damage (zombies, etc.) except players by granting all the
|
||||
health back to the villager after being harmed.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Scarpet events system
|
||||
|
||||
Provides the ability to execute specific function whenever an event occurs. The functions to be registered need to
|
||||
conform with the arguments to the event specification. When loading module functions, each function that starts
|
||||
with `__on_...` and has the required arguments, will be bound automatically. In case of player specific modules,
|
||||
all player action events will be directed to the appropriate player space, and all tick events will be executed in
|
||||
the global context, so its not a good idea to mix these two, so use either of these, or use commands to call tick
|
||||
events directly, or handle player specific data inside a module. In near future using global events
|
||||
(on_tick, on_chunk_generated) will be not allowed in player scoped apps.
|
||||
|
||||
### Event list
|
||||
|
||||
Here is a list of events that can be handled by scarpet. This list includes prefixes required by modules to autoload
|
||||
them, but you can add any function to any event if it accepts required number of parameters:
|
||||
|
||||
<pre>
|
||||
__on_tick() // can access blocks and entities in the overworld
|
||||
__on_tick_nether() // can access blocks and entities in the nether
|
||||
__on_tick_ender() // can access blocks and entities in the end
|
||||
__on_chunk_generated(x,z) // called after a chunk is promoted to the full chunk,
|
||||
// prodiving lowest x and z coords in the chunk
|
||||
// event will not work with optifine installed in the game
|
||||
// player specific callbacks
|
||||
__on_player_uses_item(player, item_tuple, hand) // right click action
|
||||
__on_player_releases_item(player, item_tuple, hand) // client action (e.g. bow)
|
||||
__on_player_finishes_using_item(player, item_tuple, hand)) // server action (e.g. food), called item is from before it is used.
|
||||
__on_player_clicks_block(player, block, face) // left click attack on a block
|
||||
__on_player_breaks_block(player, block) // called after block is broken (the caller receives previous blockstate)
|
||||
__on_player_right_clicks_block(player, item_tuple, hand, block, face, hitvec) // player right clicks block with anything
|
||||
__on_player_interacts_with_block(player, hand, block, face, hitvec) //right click on a block resulted in activation of said block
|
||||
__on_player_places_block(player, item_tuple, hand, block) // player have just placed the block.
|
||||
__on_player_interacts_with_entity(player, entity, hand)
|
||||
__on_player_attacks_entity(player, entity)
|
||||
__on_player_rides(player, forward, strafe, jumping, sneaking)
|
||||
__on_player_jumps(player)
|
||||
__on_player_deploys_elytra(player)
|
||||
__on_player_wakes_up(player)
|
||||
__on_player_starts_sneaking(player)
|
||||
__on_player_stops_sneaking(player)
|
||||
__on_player_starts_sprinting(player)
|
||||
__on_player_stops_sprinting(player)
|
||||
__on_player_drops_item(player)
|
||||
__on_player_drops_stack(player)
|
||||
__on_statistic(player, category, event, value) // player statistic changes
|
||||
</pre>
|
||||
|
||||
### `/script event` command
|
||||
|
||||
used to display current events and bounded functions. use `add_to` ro register new event, or `remove_from` to
|
||||
unbind a specific function from an event. Function to be bounded to an event needs to have the same number of
|
||||
parameters as the action is attempting to bind to (see list above). All calls in modules loaded via `/script load`
|
||||
that have functions listed above will be automatically bounded and unbounded when script is unloaded.
|
||||
@@ -0,0 +1,116 @@
|
||||
# Inventory and Items API
|
||||
|
||||
## Manipulating inventories of blocks and entities
|
||||
|
||||
Most functions in this category require inventory as the first argument. Inventory could be specified by an entity,
|
||||
or a block, or position (three coordinates) of a potential block with inventory. Player enderchest inventory require
|
||||
two arguments, keyword `'enderchest'`, followed by the player entity argument. If the entity or a block doesn't have
|
||||
an inventory, they typically do nothing and return null.
|
||||
|
||||
Most items returned are in the form of a triple of item name, count, and nbt or the extra data associated with an item.
|
||||
Manipulating of the nbt data can be costly, but retrieving them from the tuple to match other aspects is cheap
|
||||
|
||||
### `stack_limit(item)`
|
||||
|
||||
Returns number indicating what is the stack limit for the item. Its typically 1 (non-stackable), 16 (like buckets),
|
||||
or 64 - rest. It is recommended to consult this, as other inventory API functions ignore normal stack limits, and
|
||||
it is up to the programmer to keep it at bay. As of 1.13, game checks for negative numbers and setting an item to
|
||||
negative is the same as empty.
|
||||
|
||||
<pre>
|
||||
stack_limit('wooden_axe') => 1
|
||||
stack_limit('ender_pearl') => 16
|
||||
stack_limit('stone') => 64
|
||||
</pre>
|
||||
|
||||
### `item_category(item)`
|
||||
|
||||
Returns the string representing the category of a given item, like `building_blocks`, `combat`, or `tools`.
|
||||
|
||||
<pre>
|
||||
item_category('wooden_axe') => tools
|
||||
item_category('ender_pearl') => misc
|
||||
item_category('stone') => building_blocks
|
||||
</pre>
|
||||
|
||||
### `inventory_size(inventory)`
|
||||
|
||||
Returns the size of the inventory for the entity or block in question. Returns null if the block or entity don't
|
||||
have an inventory
|
||||
|
||||
<pre>
|
||||
inventory_size(player()) => 41
|
||||
inventory_size('enderchest', player()) => 27 // enderchest
|
||||
inventory_size(x,y,z) => 27 // chest
|
||||
inventory_size(block(pos)) => 5 // hopper
|
||||
</pre>
|
||||
|
||||
### `inventory_has_items(inventory)`
|
||||
|
||||
Returns true, if the inventory is not empty, false if it is empty, and null, if its not an inventory.
|
||||
|
||||
<pre> inventory_has_items(player()) => true
|
||||
inventory_has_items(x,y,z) => false // empty chest
|
||||
inventory_has_items(block(pos)) => null // stone
|
||||
</pre>
|
||||
|
||||
### `inventory_get(inventory, slot)`
|
||||
|
||||
Returns the item in the corresponding inventory slot, or null if slot empty or inventory is invalid. You can use
|
||||
negative numbers to indicate slots counted from 'the back'.
|
||||
|
||||
<pre>
|
||||
inventory_get(player(), 0) => null // nothing in first hotbar slot
|
||||
inventory_get(x,y,z, 5) => ['stone', 1, {}]
|
||||
inventory_get(player(), -1) => ['diamond_pickaxe', 1, {Damage:4}] // slightly damaged diamond pick in the offhand
|
||||
</pre>
|
||||
|
||||
### `inventory_set(inventory, slot, count, item?, nbt?)`
|
||||
|
||||
Modifies or sets a stack in inventory. specify count 0 to empty the slot. If item is not specified, keeps existing
|
||||
item, just modifies the count. If item is provided - replaces current item. If nbt is provided - adds a tag to the
|
||||
stack at slot. Returns previous stack in that slot.
|
||||
|
||||
<pre>
|
||||
inventory_set(player(), 0, 0) => ['stone', 64, {}] // player had a stack of stone in first hotbar slot
|
||||
inventory_set(player(), 0, 6) => ['diamond', 64, {}] // changed stack of diamonds in player slot to 6
|
||||
inventory_set(player(), 0, 1, 'diamond_axe','{Damage:5}') => null //added slightly damaged pick to first player slot
|
||||
</pre>
|
||||
|
||||
### `inventory_find(inventory, item, start_slot?, ), inventory_find(inventory, null, start_slot?)`
|
||||
|
||||
Finds the first slot with a corresponding item in the inventory, or if queried with null: the first empty slot.
|
||||
Returns slot number if found, or null otherwise. Optional start_slot argument allows to skip all preceeding slots
|
||||
allowing for efficient (so not slot-by-slot) inventory search for items.
|
||||
|
||||
<pre>
|
||||
inventory_find(player(), 'stone') => 0 // player has stone in first hotbar slot
|
||||
inventory_find(player(), null) => null // player's inventory has no empty spot
|
||||
while( (slot = inventory_find(p, 'diamond', slot)) != null, 41, drop_item(p, slot) )
|
||||
// spits all diamonds from player inventory wherever they are
|
||||
inventory_drop(x,y,z, 0) => 64 // removed and spawned in the world a full stack of items
|
||||
</pre>
|
||||
|
||||
### `inventory_remove(inventory, item, amount?)`
|
||||
|
||||
Removes amount (defaults to 1) of item from inventory. If the inventory doesn't have the defined amount, nothing
|
||||
happens, otherwise the given amount of items is removed wherever they are in the inventory. Returns boolean
|
||||
whether the removal operation was successful. Easiest way to remove a specific item from player inventory
|
||||
without specifying the slot.
|
||||
|
||||
<pre>
|
||||
inventory_remove(player(), 'diamond') => 1 // removed diamond from player inventory
|
||||
inventory_remove(player(), 'diamond', 100) => 0 // player doesn't have 100 diamonds, nothing happened
|
||||
</pre>
|
||||
|
||||
### `drop_item(inventory, slot, amount?, )`
|
||||
|
||||
Drops the items from indicated inventory slot, like player that Q's an item or villager, that exchanges food.
|
||||
You can Q items from block inventories as well. default amount is 0 - which is all from the slot.
|
||||
NOTE: hoppers are quick enough to pick all the queued items from their inventory anyways.
|
||||
Returns size of the actual dropped items.
|
||||
|
||||
<pre>
|
||||
inventory_drop(player(), 0, 1) => 1 // Q's one item on the ground
|
||||
inventory_drop(x,y,z, 0) => 64 // removed and spawned in the world a full stack of items
|
||||
</pre>
|
||||
@@ -0,0 +1,13 @@
|
||||
# Minecraft specific API and `scarpet` language add-ons and commands
|
||||
|
||||
Here is the gist of the Minecraft related functions. Otherwise the CarpetScript could live without Minecraft.
|
||||
|
||||
## Dimension warning
|
||||
|
||||
One note, which is important is that most of the calls for entities and blocks would refer to the current
|
||||
dimension of the caller, meaning, that if we for example list all the players using `player('all')` function,
|
||||
if a player is in the other dimension, calls to entities and blocks around that player would point incorrectly.
|
||||
Moreover, running commandblocks in the spawn chunks would mean that commands will always refer to the overworld
|
||||
blocks and entities. In case you would want to run commands across all dimensions, just run three of them,
|
||||
using `/execute in overworld/the_nether/the_end run script run ...` and query players using `player('*')`,
|
||||
which only returns players in current dimension, or use `in_dimension(expr)` function.
|
||||
@@ -0,0 +1,185 @@
|
||||
# `/script run` command
|
||||
|
||||
Primary way to input commands. The command executes in the context, position, and dimension of the executing player,
|
||||
commandblock, etc... The command receives 4 variables, `x`, `y`, `z` and `p` indicating position and
|
||||
the executing entity of the command. You will receive tab completion suggestions as you type your code suggesting
|
||||
functions and global variables. It is advisable to use `/execute in ... at ... as ... run script run ...` or similar,
|
||||
to simulate running commands in a different scope.
|
||||
|
||||
# `/script load / unload <app> (global?)`, `/script in <app>` commands
|
||||
|
||||
`load / unload` commands allow for very conventient way of writing your code, providing it to the game and
|
||||
distribute with your worlds without the need of use of commandblocks. Just place your scarpet code in the
|
||||
/scripts folder of your world files and make sure it ends with `.sc` extension. The good thing about editing that
|
||||
code is that you can no only use normal editing without the need of marking of newlines,
|
||||
but you can also use comments in your code.
|
||||
|
||||
a comment is anything that starts with a double slash, and continues to the end of the line:
|
||||
|
||||
<pre>
|
||||
foo = 1;
|
||||
//This is a comment
|
||||
bar = 2;
|
||||
// This never worked, so I commented it out
|
||||
// baz = foo()
|
||||
</pre>
|
||||
|
||||
### `/script load/unload <app> (?global)`
|
||||
|
||||
Loading operation will load that script code from disk and execute it right away. You would probably use it to load
|
||||
some stored procedures to be used for later. To reload the module, just type `/script load` again. Reloading removes
|
||||
all the current global state (globals and functions) that were added later by the module.
|
||||
|
||||
Loading a module, if it contains a `__command()` method, will attempt to registed a command with that app name,
|
||||
and register all public (no underscore) functions available in the module as subcommands. It will also bind specific
|
||||
events to the event system (check Events section for details).
|
||||
|
||||
Loaded apps have the ability to store and load external files, especially their persistent tag state. For that
|
||||
check `load_app_data` and `store_app_data` functions.
|
||||
|
||||
If an app defines `__config` method, and that method returns a map, it will be used to apply custom settings
|
||||
for this app. Currently the following options are supported:
|
||||
|
||||
* `scope`: default scope for global variables for the app, Default is 'player' which means that globals and defined
|
||||
functions will be unique for each player so that apps for each player will run in isolation. This is useful in
|
||||
tool-like applications. Another option is 'global' which shares global state for all runs on the server - applicable
|
||||
to 'block' like solutions, where custom behaviours are applied to blocks.
|
||||
* `stay_loaded`: defaults to false. If true, and `/carpet scriptsAutoload` is turned on, the following apps will
|
||||
stay loaded after startup. Otherwise, after reading a code, and fetching the config, server will drop them down.
|
||||
This is to allow to store multiple apps on the server/world and selectively decide which one should be running at
|
||||
startup. WARNING: all apps will run once at startup anyways, so be aware that their actions that are called
|
||||
statically, will be performed once anyways.
|
||||
|
||||
Unloading an app removes all of its state from the game, disables commands, and removes bounded events, and
|
||||
saves its global state. If more cleanup is needed, one can define an `__on_close()` function which will be
|
||||
executed when the module is unloaded, or server is closing, or crashing. However, there is no need to do that
|
||||
explicitly for the things mentioned in the previous statement.
|
||||
|
||||
Scripts can be loaded in shared(global) and player mode. Default is player, so all globals and stored functions are
|
||||
individual for each player, meaning scripts don't need to worry about making sure they store some intermittent
|
||||
data for each player independently. In global mode - all global values and stored functions are shared among all
|
||||
players. To access specific player data with commandblocks, use `/execute as (player) run script in (app) run ...`.
|
||||
To access global/server state, you need to disown the command from any player, so use a commandblock, or any
|
||||
arbitrary entity: `/execute as @e[type=bat,limit=1] run script in (module) globals` for instance.
|
||||
|
||||
### `/script in <app> ...`
|
||||
|
||||
Allows to run normal /script commands in a specific app, like `run, invoke,..., globals` etc...
|
||||
|
||||
# `/script invoke / invokepoint / invokearea`, `/script globals` commands
|
||||
|
||||
`invoke` family of commands provide convenient way to invoke stored procedures (i.e. functions that has been
|
||||
defined previously by any running script. To view current stored procedure set,
|
||||
run `/script globals`(or `/script globals all` to display all functions even hidden ones), to define a new stored
|
||||
procedure, just run a `/script run function(a,b) -> ( ... )` command with your procedure once, and to forget a
|
||||
procedure, use `undef` function: `/script run undef('function')`
|
||||
|
||||
### `/script invoke <fun> <args?> ...`
|
||||
|
||||
Equivalent of running `/script run fun(args, ...)`, but you get the benefit of getting the tab completion of the
|
||||
command name, and lower permission level required to run these (since player is not capable of running any custom
|
||||
code in this case, only this that has been executed before by an operator). Arguments will be checked for validity,
|
||||
and you can only pass simple values as arguments (strings, numbers, or `null` value). Use quotes to include
|
||||
whitespaces in argument strings.
|
||||
|
||||
Command will check provided arguments with required arguments (count) and fail if not enough or too much
|
||||
arguments are provided. Operators defining functions are advised to use descriptive arguments names, as these
|
||||
will be visible for invokers and form the base of understanding what each argument does.
|
||||
|
||||
`invoke` family of commands will tab complete any stored function that does not start with `'_'`, it will still
|
||||
allow to run procedures starting with `'_'` but not suggest them, and ban execution of any hidden stored procedures,
|
||||
so ones that start with `'__'`. In case operator needs to use subroutines for convenience and don't want to expose
|
||||
them to the `invoke` callers, they can use this mechanic.
|
||||
|
||||
<pre>
|
||||
/script run example_function(const, phrase, price) -> print(const+' '+phrase+' '+price)
|
||||
/script invoke example_function pi costs 5
|
||||
</pre>
|
||||
|
||||
### `/script invokepoint <fun> <coords x y z> <args?> ...`
|
||||
|
||||
It is equivalent to `invoke` except it assumes that the first three arguments are coordinates, and provides
|
||||
coordinates tab completion, with `looking at...` mechanics for convenience. All other arguments are expected
|
||||
at the end
|
||||
|
||||
### `/script invokearea <fun> <coords x y z> <coords x y z> <args?> ...`
|
||||
|
||||
It is equivalent to `invoke` except it assumes that the first three arguments are one set of ccordinates,
|
||||
followed by the second set of coordinates, providing tab completion, with `looking at...` mechanics for convenience,
|
||||
followed by any other required arguments
|
||||
|
||||
# `/script scan`, `/script fill` and `/script outline` commands
|
||||
|
||||
These commands can be used to evaluate an expression over an area of blocks. They all need to have specified the
|
||||
origin of the analyzed area (which is used as referenced (0,0,0), and two corners of an area to analyzed. If you
|
||||
would want that the script block coordinates refer to the actual world coordinates, use origin of `0 0 0`, or if
|
||||
it doesn't matter, duplicating coordinates of one of the corners is the easiest way.
|
||||
|
||||
These commands, unlike raw `/script run` are limited by vanilla fill / clone command limit of 32k blocks, which can
|
||||
be altered with carpet mod's own `/carpet fillLimit` command.
|
||||
|
||||
### `/script scan origin<x y z> corner<x y z> corner<x y z> expr`
|
||||
|
||||
Evaluates expression for each point in the area and returns number of successes (result was positive). Since the
|
||||
command by itself doesn't affect the area, the effects would be in side effects.
|
||||
|
||||
### `/script fill origin<x y z> corner<x y z> corner<x y z> "expr" <block> (? replace <replacement>)`
|
||||
|
||||
Think of it as a regular fill command, that sets blocks based on whether a result of the command was successful.
|
||||
Note that the expression is in quotes. Thankfully string constants in `scarpet` use single quotes. Can be used to
|
||||
fill complex geometric shapes.
|
||||
|
||||
### `/script outline origin<x y z> corner<x y z> corner<x y z> "expr" <block> (? replace <replacement>)`
|
||||
|
||||
Similar to `fill` command it evaluates an expression for each block in the area, but in this case setting blocks
|
||||
where condition was true and any of the neighbouring blocks were evaluated negatively. This allows to create surface
|
||||
areas, like sphere for example, without resorting to various rounding modes and tricks.
|
||||
|
||||
Here is an example of seven ways to draw a sphere of radius of 32 blocks around 0 100 0:
|
||||
|
||||
<pre>
|
||||
/script outline 0 100 0 -40 60 -40 40 140 40 "x*x+y*y+z*z < 32*32" white_stained_glass replace air
|
||||
/script outline 0 100 0 -40 60 -40 40 140 40 "x*x+y*y+z*z <= 32*32" white_stained_glass replace air
|
||||
/script outline 0 100 0 -40 60 -40 40 140 40 "x*x+y*y+z*z < 32.5*32.5" white_stained_glass replace air
|
||||
/script fill 0 100 0 -40 60 -40 40 140 40 "floor(sqrt(x*x+y*y+z*z)) == 32" white_stained_glass replace air
|
||||
/script fill 0 100 0 -40 60 -40 40 140 40 "round(sqrt(x*x+y*y+z*z)) == 32" white_stained_glass replace air
|
||||
/script fill 0 100 0 -40 60 -40 40 140 40 "ceil(sqrt(x*x+y*y+z*z)) == 32" white_stained_glass replace air
|
||||
/draw sphere 0 100 0 32 white_stained_glass replace air // fluffy ball round(sqrt(x*x+y*y+z*z)-rand(abs(y)))==32
|
||||
</pre>
|
||||
|
||||
The last method is the one that world edit is using (part of carpet mod). It turns out that the outline method
|
||||
with `32.5` radius, fill method with `round` function and draw command are equivalent
|
||||
|
||||
# `script stop/script resume` command
|
||||
|
||||
`/script stop` allows to stop execution of any script currently running that calls the `game_tick()` function which
|
||||
allows the game loop to regain control of the game and process other commands. This will also make sure that all
|
||||
current and future programs will stop their execution. Execution of all programs will be prevented
|
||||
until `/script resume` command is called.
|
||||
|
||||
Lets look at the following example. This is a program computes Fibonacci number in a recursive manner:
|
||||
|
||||
<pre>
|
||||
fib(n) -> if(n<3, 1, fib(n-1)+fib(n-2) ); fib(8)
|
||||
</pre>
|
||||
|
||||
That's really bad way of doing it, because the higher number we need to compute the compute requirements will
|
||||
rise exponentially with `n`. It takes a little over 50 milliseconds to do fib(24), so above one tick, but about
|
||||
a minute to do fib(40). Calling fib(40) will not only freeze the game, but also you woudn't be able to interrupt
|
||||
its execution. We can modify the script as follows
|
||||
|
||||
<pre>
|
||||
fib(n) -> ( game_tick(50); if(n<3, 1, fib(n-1)+fib(n-2) ) ); fib(40)
|
||||
</pre>
|
||||
|
||||
But this would never finish as such call would finish after `~ 2^40` ticks. To make our computations responsive,
|
||||
yet able to respond to user interactions, other commands, as well as interrupt execution, we could do the following:
|
||||
|
||||
<pre>
|
||||
fib(n) -> ( if(n==23, game_tick(50) ); if(n<3, 1, fib(n-1)+fib(n-2) ) ); fib(40)
|
||||
</pre>
|
||||
|
||||
This would slow down the computation of fib(40) from a minute to two, but allows the game to keep continue running
|
||||
and be responsive to commands, using about half of each tick to advance the computation. Obviously depending on the
|
||||
problem, and available hardware, certain things can take more or less time to execute, so portioning of work with
|
||||
calling `gametick` should be balanced in each case separately
|
||||
Reference in new issue
Block a user