icybear/fabric-carpet
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
gnembon committed 2019-10-15 13:57:34 -03:00
1 parent 4549c9948c
commit 82dfb8266c
3 files changed
+65 -9
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/main/java/carpet/script/CarpetExpression.java
+39
View File
@@ -433,6 +433,14 @@ public class CarpetExpression
* pos(players()) => l(12.3, 45.6, 32.05)
* pos(block('stone')) => Error: Cannot fetch position of an unrealized block
* </pre>
* <h3><code>pos_offset(pos, direction, amount?)</code></h3>
* <p>Returns a coords triple that is offset in a specified <code>direction</code> by <code>amount</code> of blocks.
* The default offset amount is 1 block. To offset into opposite facing, use negative numbers for the <code>amount</code>.
* </p>
* <pre>
* pos_offset(block(0,5,0), 'up', 2) =&gt; l(0,7,0)
* pos_offset(l(0,5,0), 'up', -2 ) =&gt; l(0,3,0)
* </pre>
* <h3><code>block_properties(pos)</code></h3>
* <p>Returns a list of available block properties for a particular block. If a block has no properties, returns an empty list.</p>
* <h3><code>property(pos, name)</code></h3>
@@ -1087,6 +1095,13 @@ public class CarpetExpression
* inventory_size(x,y,z) =&gt; 27 // chest
* inventory_size(block(pos)) =&gt; 5 // hopper
* </pre>
* <h3><code>inventory_has_items(inventory)</code></h3>
* <p>Returns true, if the inventory is not empty, false if it is empty, and null, if its not an inventory.</p>
* <pre>
* inventory_has_items(player()) =&gt; true
* inventory_has_items(x,y,z) =&gt; false // empty chest
* inventory_has_items(block(pos)) =&gt; null // stone
* </pre>
* <h3><code>inventory_get(inventory, slot)</code></h3>
* <p>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'.</p>
@@ -2427,11 +2442,22 @@ public class CarpetExpression
* <h3><code>print(expr)</code></h3>
* <p>Displays the result of the expression to the chat. Overrides default <code>scarpet</code> behaviour of
* sending everyting to stderr.</p>
* <h3><code>logger(expr)</code></h3>
* <p>Prints the message to system logs, and not to chat.</p>
* <h3><code>run(expr)</code></h3>
* <p>Runs a command from the string result of the <code>expr</code> expression, and returns its success count</p>
* <h3><code>save()</code></h3>
* <p>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.</p>
* <h3><code>load_app_data(), load_app_data(file)</code></h3>
* <p>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
* floder.</p>
* <p> You can use app data to save non-vanilla information separately from the world and other scripts.</p>
* <h3><code>store_app_data(tag), store_app_data(tag, file)</code></h3>
* <p>Stores the app data associated with the app from the world /scripts folder. With the <code>file</code> parameter
* saves immediately and with every call, without <code>file</code> 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.</p>
* <h3><code>tick_time()</code></h3>
* <p>Returns game tick counter. Can be used to run certain operations every n-th ticks, or to count in-game time</p>
* <h3><code>game_tick(mstime?)</code></h3>
@@ -3148,6 +3174,19 @@ public class CarpetExpression
* <p>Loading a module, if it contains a <code>__command()</code> method, will attempt to registed a command with that
* module 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).</p>
* <p>If an app defines <code>__config</code> method, and that method returns a map, it will be used to apply custom
* settings for this app. Currently the following options are supported:</p>
* <ul>
* <li><code>scope</code>: 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.</li>
* <li><code>stay_loaded</code>: defaults to false. If true, and <code>/carpet scriptsAutoload</code> 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.</li>
* </ul>
* <p>Unloading a module removes all of its state from the game, disables commands, and removes bounded events</p>
* <p>Scripts can be loaded in shared 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
src/main/java/carpet/script/Expression.java
+25 -8
View File
@@ -1090,12 +1090,14 @@ public class Expression implements Cloneable
* <h3><code>Get, Accessor Operator :</code></h3>
* <p>Operator version of the <code>get(...)</code> function to access elements of lists, maps, and potentially other
* containers (i.e. NBTs). It is important to distinguish from <code>~</code> operator, which is a matching operator,
* which is expected to perform some extra computations to retrieve the result, while <code>.</code> should be
* which is expected to perform some extra computations to retrieve the result, while <code>:</code> should be
* straightforward and immediate, and the source object should behave like a container and support full container
* API, meaning <code>get(...)</code>, <code>put(...)</code>, <code>delete(...)</code>,
* and <code>has(...)</code> functions</p>
* <p>WARNING: Unlike for some languages, where item access operator can be an L-value, to assign new values to
* container elements, use <code>put</code> function instead, i.e. <code>a:1='foo'</code> won't work.</p>
* <p>For certain operators and functions (get, put, delete, has, =, +=) objects can use <code>:</code> annotated
* fields as l-values, meaning construct like <code>foo:0 = 5</code>, would act like <code>put(foo, 0, 5)</code>,
* rather than <code>get(foo, 0) = 5</code>, which would result in an error.</p>
* <p>TODO: add more information about l-value behaviour.</p>
*
* <h3><code>Matching Operator ~</code></h3>
* <p>This operator should be understood as 'matches', 'contains', 'is_in',
@@ -2025,7 +2027,7 @@ public class Expression implements Cloneable
* <p>Here is a list of operations that work on all types of containers: lists, maps, as well as other Minecraft
* specific modifyable containers, like NBTs</p>
*
* <h3><code>get(container, address), ':' operator</code></h3>
* <h3><code>get(container, address, ...), get(lvalue), ':' operator</code></h3>
* <p>Returns the value at <code>address</code> element from the <code>value</code>.
* For lists it indicates an index, use negative numbers to reach elements from the end of the list. <code>get</code>
* call will always be able to find the index. In case there is few items, it will loop over </p>
@@ -2034,6 +2036,9 @@ public class Expression implements Cloneable
* nbt path to query,
* returning null, if path is not found, one value if there was one match, or list of values if result is a list.
* Returned elements can be of numerical type, string texts, or another compound nbt tags</p>
* <p>In case to simplify the access with nested objects, you can add chain of addresses to the arguments of
* <code>get</code> rather than calling it multiple times. <code>get(get(foo,a),b)</code> is equivalent to
* <code>get(foo, a, b)</code>, or <code>foo:a:b</code>.</p>
* <pre>
* get(l(range(10)), 5) =&gt; 5
* get(l(range(10)), -1) =&gt; 9
@@ -2045,17 +2050,24 @@ public class Expression implements Cloneable
* get(m( l('foo',2), l('bar',3), l('baz',4) ), 'bar') =&gt; 3
* </pre>
*
* <h3><code>has(container, address)</code></h3>
* <h3><code>has(container, address, ...), has(lvalue)</code></h3>
* <p>Similar to <code>get</code>, but returns boolean value indicating if the given index / key / path is in the
* container. Can be used to determine if <code>get(...)==null</code> means the element doesn't exist, or the stored value
* for this address is <code>null</code>, and is cheaper to run than <code>get</code></p>
* for this address is <code>null</code>, and is cheaper to run than <code>get</code>.</p>
* <p>Like get, it can accept multiple addresses for chains in nested containers. In this case <code>has(foo:a:b)</code>
* is equivalent to <code>has(get(foo,a), b)</code> or <code>has(foo, a, b)</code></p>
*
* <h3><code>delete(container, address)</code></h3>
* <h3><code>delete(container, address, ...), delete(lvalue)</code></h3>
* <p>Removes specific entry from the container. For the lists - removes the element and shrinks it. For maps, it
* removes the key from the map, and for nbt - removes content from a given path. For lists and maps returns previous
* entry at the address, for nbt's - number of removed objects, with 0 indicating that the original value was unaffected.</p>
* <p>Like with the <code>get</code> and <code>has</code>, <code>delete</code> can accept chained addresses, as well as
* l-value container access, removing the value
* from the leaf of the path provided, so <code>delete(foo, a, b)</code> is the same as <code>delete(get(foo,a),b)</code>
* or <code>delete(foo:a:b)</code></p>
* <p>Returns true, if container was changed, false, if it was left unchanged, and null if operation was invalid.</p>
*
* <h3><code>put(container, address, value), put(container, address, value, mode)</code></h3>
* <h3><code>put(container, address, value), put(container, address, value, mode), put(lvalue, value)</code></h3>
* <p><u><b>Lists</b></u></p>
* <p>Modifies the container by replacing the value under the address with the supplied <code>value</code>.
* For lists, a valid index is required, but can be negative as well to indicate positions from the end of the list.
@@ -2072,6 +2084,11 @@ public class Expression implements Cloneable
* extending the list by this amount of items. Again use <code>null</code> address/index to point to the end of
* the list</li>
* </ul>
* <p>Due to the extra mode parameter, there is no chaining for <code>put</code>, but you can still use l-value
* container access to indicate container and address, so <code>put(foo, key, value)</code> is the same as
* <code>put(foo:key, value)</code> or <code>foo:key=value</code></p>
* <p>Returns true, if container got modified, false otherwise, and null if operation was invalid.</p>
*
* <p><u><b>Maps</b></u></p>
* <p>For maps there are no modes available (yet, seems there is no reason to). It replaces the value under the supplied
* key (address), or sets it if not currently present.</p>