### Example carpet.conf Configuration

Source: https://github.com/gnembon/fabric-carpet/wiki/Carpet-Configuration

Example content for the carpet.conf file located in the world directory.

```text
defaultLoggers mobcaps,tps
fastRedstoneDust true
onePlayerSleeping true
combineXPOrbs true
leadFix true
antiCheatDisabled true
persistentParrots true
xpNoCooldown true
ctrlQCraftingFix true
hopperCounters true
lagFreeSpawning true
```

--------------------------------

### Starting a Fabric Server

Source: https://github.com/gnembon/fabric-carpet/wiki/How-to-install-fabric-carpet-on-a-(remote)-server

Use this command to start the Fabric server. Adjust memory allocation (-Xms and -Xmx) as needed.

```bash
java -Xms1G -Xmx4G -jar fabric-server-launch.jar nogui
```

--------------------------------

### Custom Events Example

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Events.md

Example demonstrating how to communicate between different instances of the same player-scoped app using custom events.

```APIDOC
## Custom events example

The following example shows how you can communicate between different instances of the same player scoped app. It is important to note that signals can trigger other apps as well, assuming the name of the event matches. In this case, the request name is called `tp_request` and is triggered with a command.

```lua
// tpa.sc
global_requester = null;
__config() -> {
	'commands' -> {
		'<player>' -> _(to) -> signal_event('tp_request', to, player()),
      'accept' -> _() -> if(global_requester, 
         run('tp '+global_requester~'command_name'); 
         global_requester = null
      )
	},
   'arguments' -> {
      'player' -> {'type' -> 'players', 'single' -> true}
   }
};
handle_event('tp_request', _(req) -> (
   global_requester = req;
   print(player(), format(
      'w '+req+' requested to teleport to you. Click ',
      'yb here', '^yb here', '!/tpa accept',
      'w  to accept it.'
   ));
));
```
```

--------------------------------

### Scarpet App Code Example

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/Overview.md

This is an example of a Scarpet app file (`.sc`) that can be placed in the `/scripts` folder. It demonstrates a loop with random number generation and a function to check for zero.

```scarpet
run_program() -> (
  loop( 10,
    // looping 10 times
    // comments are allowed in scripts located in world files
    // since we can tell where that line ends
    foo = floor(rand(10));
    check_not_zero(foo);
    print(_+' - foo: '+foo);
    print('  reciprocal: '+  _/foo )
  )
);
check_not_zero(foo) -> (
  if (foo==0, foo = 1)
)
```

--------------------------------

### Example: Kill Entities in Area

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Entities.md

An example demonstrating how to kill all entities within a specified area using entity_area and query.

```python
map(entities_area('*',x,y,z,30,30,30),run('kill '+query(_,'id')))
```

--------------------------------

### Format if-statements

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Examples showing how whitespace and brackets can be used to improve the readability of complex if-statements.

```scarpet
if(x<y+6,set(x,8+y,z,'air');plop(x,top('surface',x,z),z,'birch'),sin(query(player(),'yaw'))>0.5,plop(0,0,0,'boulder'),particle('fire',x,y,z))
```

```scarpet
if(   x<y+6,
           set(x,8+y,z,'air');
           plop(x,top('surface',x,z),z,'birch'),
      sin(query(player(),'yaw'))>0.5,
           plop(0,0,0,'boulder'),
      particle('fire',x,y,z)
)
```

```scarpet
if
(   x<y+6,
    (
        set(x,8+y,z,'air');
        plop(x,top('surface',x,z),z,'birch')
    ),
    // else if
    sin(query(player(),'yaw'))>0.5,
    (
        plop(0,0,0,'boulder')
    ),
    // else
    particle('fire',x,y,z)
)
```

--------------------------------

### Create Datapack with Recipe

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

Example of creating a datapack that adds a custom crafting recipe for cobwebs using string.

```javascript
script run create_datapack('craftable_cobwebs', {
    'data' -> { 'scarpet' -> { 'recipes' -> { 'cobweb.json' -> {
        'type' -> 'crafting_shaped',
        'pattern' -> [
            'SSS',
            'SSS',
            'SSS'
        ],
        'key' -> {
            'S' -> {
                'item' -> 'minecraft:string'
            }
        },
        'result' -> {
            'item' -> 'minecraft:cobweb',
            'count' -> 1
        }
    } } } } 
});
```

--------------------------------

### Example trace output

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

The structure of the _trace variable when an exception is caught.

```json
{stack: [[<app>, inner_call, 1, 14]], locals: {_a: 0, aaa: booyah, _: 1, _y: 0, _i: 1, _x: 0, _z: 0}, token: [item_tags, 5, 23]}
```

--------------------------------

### Example of throw() usage

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/FunctionsAndControlFlow.md

Illustrates how to throw exceptions with different argument combinations: no arguments, type and value, or subtype, type, and value.

```scarpet
throw()
```

```scarpet
throw('user_exception', 'An error occurred')
```

```scarpet
throw('custom_subtype', 'user_exception', 'A custom user error')
```

--------------------------------

### Manage Bossbars

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Examples of creating, querying, and modifying bossbar properties including style, progress, visibility, and player assignment.

```scarpet
bossbar('script:test','style','notched_12')
bossbar('script:test','value',74)
bossbar('script:test','name',format('rb Test'))  -> Change text
bossbar('script:test','visible',false)  -> removes visibility, but keeps players
bossbar('script:test','players',player('all'))  -> Visible for all players
bossbar('script:test','players',player('Steve'))  -> Visible for Steve only 
bossbar('script:test','players',null)  -> Invalid player, removing all players
bossbar('script:test','add_player',player('Alex'))  -> Add Alex to the list of players that can see the bossbar
bossbar('script:test','remove')  -> remove bossbar 'script:test'
for(bossbar(),bossbar(_,'remove'))  -> remove all bossbars
```

--------------------------------

### Create Datapack with Loot Table

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

This example demonstrates creating a datapack that modifies the loot table for silverfish to drop gravel.

```javascript
script run create_datapack('silverfishes_drop_gravel', {
    'data' -> { 'minecraft' -> { 'loot_tables' -> { 'entities' -> { 'silverfish.json' -> {
        'type' -> 'minecraft:entity',
        'pools' -> [
            {
                'rolls' -> {
                    'min' -> 0,
                    'max' -> 1
                },
                'entries' -> [
                    {
                        'type' -> 'minecraft:item',
                        'name' -> 'minecraft:gravel'
                    }
                ]
            }
        ]
    } } } } }
});
```

--------------------------------

### Define app libraries

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Overview.md

Specifies external libraries or apps to be downloaded during installation, supporting URLs or internal paths.

```scarpet
'libraries' -> [
        {
            'source' -> '/tutorial/carpets.sc'
        },
        {
            'source' -> '/fundamentals/heap.sc',
            'target' -> 'heap-lib.sc'
        }
    ]
```

--------------------------------

### Modify containers with put()

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/Containers.md

Examples demonstrating the use of put() on lists, maps, and NBT tags with various modes and addressing strategies.

```scarpet
a = [1, 2, 3]; put(a, 1, 4); a  => [1, 4, 3]
a = [1, 2, 3]; put(a, null, 4); a  => [1, 2, 3, 4]
a = [1, 2, 3]; put(a, 1, 4, 'insert'); a  => [1, 4, 2, 3]
a = [1, 2, 3]; put(a, null, [4, 5, 6], 'extend'); a  => [1, 2, 3, 4, 5, 6]
a = [1, 2, 3]; put(a, 1, [4, 5, 6], 'extend'); a  => [1, 4, 5, 6, 2, 3]
a = [[0,0,0],[0,0,0],[0,0,0]]; put(a:1, 1, 1); a  => [[0, 0, 0], [0, 1, 0], [0, 0, 0]]
a = {1,2,3,4}; put(a, 5, null); a  => {1: null, 2: null, 3: null, 4: null, 5: null}
tag = nbt('{}'); put(tag, 'BlockData.Properties', '[1,2,3,4]'); tag  => {BlockData:{Properties:[1,2,3,4]}}
tag = nbt('{a:[{lvl:3},{lvl:5},{lvl:2}]}'); put(tag, 'a[].lvl', 1); tag  => {a:[{lvl:1},{lvl:1},{lvl:1}]}
tag = nbt('{a:[{lvl:[1,2,3]},{lvl:[3,2,1]},{lvl:[4,5,6]}]}'); put(tag, 'a[].lvl', 1, 2); tag
     => {a:[{lvl:[1,2,1,3]},{lvl:[3,2,1,1]},{lvl:[4,5,1,6]}]}
tag = nbt('{a:[{lvl:[1,2,3]},{lvl:[3,2,1]},{lvl:[4,5,6]}]}'); put(tag, 'a[].lvl[1]', 1); tag
     => {a:[{lvl:[1,1,3]},{lvl:[3,1,1]},{lvl:[4,1,6]}]}
```

--------------------------------

### Resource Downloading Configuration

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Overview.md

Specifies downloadable resources for app installation, including their source and target locations.

```APIDOC
## 'resources'

### Description
List of all downloadable resources when installing the app from an app store. List of resources needs to be in a list and contain map-like resource descriptors.

### Resource Descriptor Structure
```
{
    'source': 'URL | /absolute/path | relative/path',
    'target': 'path/in/app/data',
    'shared': true | false
}
```

- **source**: Resource location. Can be an arbitrary URL (starting with `http://` or `https://`), an absolute path in the app store (starting with `/`), or a relative path in the same folder as the app.
- **target**: Path in app data or shared app data folder. If not specified, it will be placed in the main data folder with its original name.
- **shared**: If specified and `true`, resources will be re-downloaded when the app is re-downloaded.

**Note:** Currently, app resources are only downloaded when using the `/script download` command.
```

--------------------------------

### Create Datapack with Custom Dimension (1.17)

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

Example for creating a datapack that defines a custom dimension for Minecraft 1.17. Note that worldgen changes are not supported by vanilla on server start.

```javascript
// 1.17
script run create_datapack('funky_world',  {
    'data' -> { 'minecraft' -> { 'dimension' -> { 'custom_ow.json' -> {
        'type' -> 'minecraft:the_end',
        'generator' -> {
            'biome_source' -> {
                 'seed' -> 0,
                 'large_biomes' -> false,
                 'type' -> 'minecraft:vanilla_layered'
            },
            'seed' -> 0,
            'settings' -> 'minecraft:nether',
            'type' -> 'minecraft:noise'
    } } } } } 
});

// 1.18
script run a() -> create_datapack('funky_world',  {
   'data' -> { 'minecraft' -> { 'dimension' -> { 'custom_ow.json' -> {
      'type' -> 'minecraft:overworld',
         'generator' -> {
            'biome_source' -> {
               'biomes' -> [
                  {
                     'parameters' -> {
                        'erosion' -> [-1.0,1.0], 
                        'depth' -> 0.0, 
                        'weirdness' -> [-1.0,1.0],
                        'offset' -> 0.0,
                        'temperature' -> [-1.0,1.0],
                        'humidity' -> [-1.0,1.0],
                        'continentalness' -> [ -1.2,-1.05]
                     },
                     'biome' -> 'minecraft:mushroom_fields'
                  }
               ],
               'type' -> 'minecraft:multi_noise'
            },
            'seed' -> 0,
            'settings' -> 'minecraft:overworld',
            'type' -> 'minecraft:noise'
         }
     } } } } 
});
enable_hidden_dimensions();  => ['funky_world']
```

--------------------------------

### Resource Descriptor Example

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Defines how to specify downloadable resources for an app. Resources can be sourced from URLs, absolute paths, or relative paths within the app's directory. The target specifies the path within the app data folder.

```plaintext
'resources' -> [
        {
            'source' -> 'https://raw.githubusercontent.com/gnembon/fabric-carpet/master/src/main/resources/assets/carpet/icon.png',
            'target' -> 'foo/photos.zip/foo/cm.png',
        },
        {
            'source' -> '/survival/README.md',
            'target' -> 'survival_readme.md',
            'shared' -> true,
        },
        {
            'source' -> 'circle.sc', // Relative path
            'target' -> 'apps/circle.sc',
        },
    ]
```

--------------------------------

### Configure App Autoloading

Source: https://github.com/gnembon/fabric-carpet/wiki/Installing-carpet-scripts-in-your-world

Use this function at the start of a script to prevent it from loading automatically when the world starts.

```py
__config() -> {'stay_loaded' -> false};
```

--------------------------------

### min and max with assignment example

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/Math.md

Demonstrates the ability of `min` and `max` functions to be used as LHS of assignments, modifying the original variables.

```plaintext
a = 1; b = 2; min(a,b) = 3; [a,b]  => [3, 2]
```

```plaintext
a = 1; b = 2; fun(x, min(a,b)) -> [a,b]; fun(3,5)  => [5, 0]
```

--------------------------------

### Execute Vanilla Commands

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Shows how to run Minecraft commands and capture their output and errors. Includes examples of successful commands, a failed command, and the behavior when run from within a script.

```javascript
run('fill 1 1 1 10 10 10 air') -> [123, ["Successfully filled 123 blocks"], null]
run('give @s stone 4') -> [1, ["Gave 4 [Stone] to gnembon"], null]
run('seed') -> [-170661413, [Seed: [4031384495743822299]], null]
run('sed') -> [-1, [], "sed<--[HERE]"] // wrong command
```

```javascript
/script run run('setblock 0 0 0 stone') -> null
```

```javascript
/script run schedule(0, _() -> print(run('setblock 0 0 0 stone'))) -> [1, [Changed the block at 0, 0, 0], null]
```

--------------------------------

### Importing and Calling Functions Across Modules

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Demonstrates how to import functions between modules and the issues that arise when passing function names versus function references.

```Scarpet
//app.sc
import('lib', 'callme');
foo(x) -> x*x;
test() -> callme('foo' , 5);
```

```Scarpet
//lib.scl
callme(fun, arg) -> call(fun, arg);
```

```Scarpet
//lib.scl
import('app','foo');
callme(fun, arg) -> call(fun, arg);
```

```Scarpet
//app.sc
import('lib', 'callme');
foo(x) -> x*x;
test() -> callme(_(x) -> foo(x), 5);
```

```Scarpet
//lib.scl
callme(fun, arg) -> call(fun, arg);
```

```Scarpet
//app.sc
import('lib', 'callme');
global_foohandler = (foo(x) -> x*x);
test() -> callme(global_foohandler, 5);
```

--------------------------------

### Create and Open a Screen

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Initializes a new screen for a player with an optional callback function to handle interactions.

```scarpet
create_screen(player, type, name, callback?)
```

--------------------------------

### Get Block Blast Resistance

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/BlocksAndWorldAccess.md

Use `blast_resistance(pos)` to get the numeric value indicating the block's resistance to explosions at the given position.

```java
blast_resistance(pos)
```

--------------------------------

### Get Block Light Level

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/BlocksAndWorldAccess.md

Use `block_light(pos)` to get the light level originating from artificial sources like torches at the given position.

```java
block_light(pos)
```

--------------------------------

### Example of try() with different catch types

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/FunctionsAndControlFlow.md

Demonstrates catching all exceptions with try(expr, 'exception', catch_expr) and only user exceptions with try(expr, null, catch_expr).

```scarpet
inner_call() ->
(
   aaa = 'booyah';
   try(
      for (range(10), item_tags('stick'+_*'k'));
   , 
      print(_trace) // not caught, only catching user_exceptions
   )
);

outer_call() -> 
(
   try(
      inner_call()
   , 'exception', // catching everything
      print(_trace)
   )
);
```

--------------------------------

### Get valid living entities

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Use `entity_types('valid', 'living')` to get a list of all valid (not dead) entities that resemble creatures. The returned list can be used as a descriptor.

```javascript
entity_types('valid', 'living')
```

--------------------------------

### Execute Vanilla Commands with run()

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

Executes Minecraft commands and returns a result triple. Commands run directly from /script may be scheduled rather than executed immediately.

```scarpet
run('fill 1 1 1 10 10 10 air') -> [123, ["Successfully filled 123 blocks"], null]
run('give @s stone 4') -> [1, ["Gave 4 [Stone] to gnembon"], null]
run('seed') -> [-170661413, [Seed: [4031384495743822299]], null]
run('sed') -> [-1, [], "sed<--[HERE]"] // wrong command

/script run run('setblock 0 0 0 stone') -> null
/script run schedule(0, _() -> print(run('setblock 0 0 0 stone'))) -> [1, [Changed the block at 0, 0, 0], null]
```

--------------------------------

### Get Biome by Block or Name

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/BlocksAndWorldAccess.md

Use `biome(block)` or `biome(name)` to get the biome at a specific location or for a given biome name. Throws 'unknown_biome' if invalid.

```java
biome(block)
```

```java
biome(name)
```

--------------------------------

### Get Element from List or Map in Scarpet

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/Containers.md

Use `get` or the ':' operator to retrieve elements by index (lists) or key (maps). Negative indices access elements from the end. For lists, out-of-bounds indices wrap around. Supports chained addresses for nested structures.

```scarpet
get([range(10)], 5)  => 5
get([range(10)], -1)  => 9
get([range(10)], 10)  => 0
[range(10)]:93  => 3
get(player() ~ 'nbt', 'Health') => 20 // inefficient way to get player health, use player() ~ 'health' instead
get({ 'foo' -> 2, 'bar' -> 3, 'baz' -> 4 }, 'bar')  => 3
```

--------------------------------

### GET /item_tags

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Queries tags associated with a specific item.

```APIDOC
## GET /item_tags

### Description
Returns a list of tags an item belongs to, or checks if an item matches a specific tag.

### Method
GET

### Endpoint
/item_tags

### Parameters
#### Query Parameters
- **item** (string) - Required - The item identifier.
- **tag** (string) - Optional - The specific tag to check against.
```

--------------------------------

### Loading and Invoking a Scarpet App

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/Overview.md

These commands show how to load a Scarpet app named 'foo' from the scripts folder and then invoke a specific function within it.

```bash
/script load foo
/script in foo invoke run_program
```

--------------------------------

### Define Simple Commands

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Overview.md

Use `__command()` to register a root command and public functions as subcommands. Arguments are parsed from a single greedy string.

```lua
__command() -> 'root command'
foo() -> 'running foo';
bar(a, b) -> a + b;
baz(a, b) -> // same thing
(
    print(a+b);
    null
)
```

--------------------------------

### GET /crafting_remaining_item

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Checks if an item leaves a remainder in the crafting grid.

```APIDOC
## GET /crafting_remaining_item

### Description
Returns the item tuple that remains in the crafting window after use, or null if none.

### Method
GET

### Endpoint
/crafting_remaining_item

### Parameters
#### Query Parameters
- **item** (string) - Required - The item used as a crafting ingredient.
```

--------------------------------

### Carpet Mod Script Outline Command Examples

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/ScriptCommand.md

Demonstrates seven methods to draw a sphere of radius 32 around a specific coordinate using the 'outline' and 'fill' commands, highlighting variations in expression evaluation and block replacement.

```scarpet
/script outline 0 100 0 -40 60 -40 40 140 40 "x*x+y*y+z*z <  32*32" white_stained_glass replace air
```

```scarpet
/script outline 0 100 0 -40 60 -40 40 140 40 "x*x+y*y+z*z <= 32*32" white_stained_glass replace air
```

```scarpet
/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
```

```scarpet
/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
```

```scarpet
/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
```

```scarpet
/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
```

```scarpet
/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
```

--------------------------------

### Configuring Vanilla Server Jar Name

Source: https://github.com/gnembon/fabric-carpet/wiki/How-to-install-fabric-carpet-on-a-(remote)-server

Specify the name of the vanilla server jar in this properties file if it's not named 'server.jar'.

```properties
serverJar=minecraft_server_1.14.4.jar
```

--------------------------------

### GET /stack_limit

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves the maximum stack size for a given item.

```APIDOC
## GET /stack_limit

### Description
Returns the stack limit for the specified item (e.g., 1, 16, or 64).

### Method
GET

### Endpoint
/stack_limit

### Parameters
#### Query Parameters
- **item** (string) - Required - The item identifier.
```

--------------------------------

### Block State API

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Functions to get and set properties of blocks.

```APIDOC
## Block State Management

### `block_state(block)`

**Description**: Returns a map of all properties and their values for a given block.

**Parameters**:
- **block** (block object or coordinates) - Required - The block to query.

**Returns**: A map of property names to their string values. Returns an empty map if the block has no properties.

### `block_state(block, property)`

**Description**: Returns the string value of a specific property for a given block.

**Parameters**:
- **block** (block object or coordinates) - Required - The block to query.
- **property** (string) - Required - The name of the property to retrieve.

**Returns**: A string value of the property, or `null` if the property is not applicable.

**Example**:
```
block_state(x,y,z,'half') // Returns the value of the 'half' property
block_state('iron_trapdoor','half') // Returns 'top' or 'bottom'
```

### `block_state(block_name)`

**Description**: Returns the default state properties for a given block name.

**Parameters**:
- **block_name** (string) - Required - The name of the block.

**Returns**: A map of default property names to their string values.

**Throws**:
- `unknown_block`: If the provided block name is not valid.

**Example**:
```
block_state('iron_trapdoor') // Returns default properties for iron_trapdoor
```
```

--------------------------------

### Define and use __holding_right_tool in-game

Source: https://github.com/gnembon/fabric-carpet/wiki/Checking-if-a-player-is-holding-the-right-tool

Demonstrates how to define the `__holding_right_tool` function using `/script run` and then how to call it to check if a specific player is holding a pickaxe.

```bash
/script run __holding_right_tool(player, tool) -> (player ~ 'holds'):0 ~ tool
/script run __holding_right_tool(player('gnembon'), '_pickaxe')
```

--------------------------------

### Player Sprinting Events

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Events.md

Events triggered when a player starts or stops sprinting.

```APIDOC
## `__on_player_starts_sprinting(player)`

### Description
Triggered when a player starts sprinting.

### Method
EVENT

### Parameters
- **player** (Player) - The player starting to sprint.

## `__on_player_stops_sprinting(player)`

### Description
Triggered when a player stops sprinting.

### Method
EVENT

### Parameters
- **player** (Player) - The player stopping to sprint.
```

--------------------------------

### Player Sneaking Events

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Events.md

Events triggered when a player starts or stops sneaking.

```APIDOC
## `__on_player_starts_sneaking(player)`

### Description
Triggered when a player starts sneaking.

### Method
EVENT

### Parameters
- **player** (Player) - The player starting to sneak.

## `__on_player_stops_sneaking(player)`

### Description
Triggered when a player stops sneaking.

### Method
EVENT

### Parameters
- **player** (Player) - The player stopping to sneak.
```

--------------------------------

### Create a chest click event GUI

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Inventories.md

Uses a generic_9x6 screen to toggle glass pane items in slots upon pickup actions.

```scarpet
__command() -> (
    create_screen(player(),'generic_9x6',format('db Test'),_(screen, player, action, data) -> (
        print(player('all'),str('%s
%s
%s',player,action,data)); //for testing
        if(action=='pickup',
            inventory_set(screen,data:'slot',1,if(inventory_get(screen,data:'slot'),'air','red_stained_glass_pane'));
        );
        'cancel'
    ));
);
```

--------------------------------

### GET /recipe_data

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves recipe information for a specific item or recipe name.

```APIDOC
## GET /recipe_data

### Description
Returns all recipes matching an item or recipe name, filtered by type.

### Method
GET

### Endpoint
/recipe_data

### Parameters
#### Query Parameters
- **item** (string) - Required - The item or recipe name.
- **type** (string) - Optional - The recipe type (e.g., 'crafting', 'smelting', 'blasting', 'smoking', 'campfire_cooking', 'stonecutting', 'smithing').
```

--------------------------------

### GET /item_list

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves a list of all items in the game or items matching a specific tag.

```APIDOC
## GET /item_list

### Description
Returns a list of all items in the game. If an optional tag is provided, it returns only items matching that tag.

### Method
GET

### Endpoint
/item_list

### Parameters
#### Query Parameters
- **tag** (string) - Optional - The item tag to filter by.
```

--------------------------------

### Create a generic_3x3 cursor stack manipulator

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Inventories.md

Demonstrates how to manipulate the cursor stack item within a 3x3 GUI, including a blinking effect.

```scarpet
__command() -> (
    screen = create_screen(player(),'generic_3x3','Title',_(screen, player, action, data) -> (
        if(action=='pickup',
            // set slot to the cursor stack item
            inventory_set(screen,data:'slot',1,inventory_get(screen,-1):0);
        );
        'cancel'
    ));

    task(_(outer(screen))->(
        // keep the cursor stack item blinking
        while(screen_property(screen,'open'),100000,
            inventory_set(screen,-1,1,'red_concrete');
            sleep(500);
            inventory_set(screen,-1,1,'lime_concrete');
            sleep(500);
        );
    ));
);
```

--------------------------------

### c_for(init, condition, increment, body)

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/language/LoopsAndHigherOrderFunctions.md

C-style loop implementation.

```APIDOC
## c_for(init, condition, increment, body)

### Description
Mimics C-style for loops. Returns the number of iterations performed.

### Parameters
- **init** (expression) - Required - Initialization expression.
- **condition** (expression) - Required - Loop condition.
- **increment** (expression) - Required - Increment expression.
- **body** (expression) - Required - The code block to execute.
```

--------------------------------

### Get Entity Air

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves the remaining air for an entity. Returns `null` if not applicable.

```javascript
query(e, 'air')
```

--------------------------------

### Get Player Absorption

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves the player's absorption health (yellow hearts).

```javascript
query(e, 'absorption')
```

--------------------------------

### Create Basic Datapack

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

Use this to create a simple datapack with JSON content. The data map defines the file structure and content.

```javascript
script run create_datapack('foo', 
{
    'foo' -> { 'bar.json' -> {
        'c' -> true,
        'd' -> false,
        'e' -> {'foo' -> [1,2,3]},
        'a' -> 'foobar',
        'b' -> 5
    } }
})
```

--------------------------------

### Get Entity Health

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves the remaining health of an entity. Returns `null` if not applicable.

```javascript
query(e, 'health')
```

--------------------------------

### Accepting the EULA

Source: https://github.com/gnembon/fabric-carpet/wiki/How-to-install-fabric-carpet-on-a-(remote)-server

Set 'eula' to 'true' in the 'eula.txt' file to accept the Minecraft End User License Agreement.

```properties
eula=true
```

--------------------------------

### Weather Control API

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Functions to get and set the current weather conditions in the game.

```APIDOC
## Weather Functions

### `weather()`

**Description**: Returns the current weather condition.

**Returns**: A string representing the current weather: 'clear', 'rain', or 'thunder'. If thundering, it always returns 'thunder'.

### `weather(type)`

**Description**: Returns the number of remaining ticks for a specified weather type.

**Parameters**:
- **type** (string) - Required - The weather type to query ('clear', 'rain', or 'thunder').

**Returns**: An integer representing the remaining ticks for the given weather type.

### `weather(type, ticks)`

**Description**: Sets the weather to a specified type for a given number of ticks.

**Parameters**:
- **type** (string) - Required - The weather type to set ('clear', 'rain', or 'thunder').
- **ticks** (integer) - Required - The duration in ticks for the weather to last.

**Example Usage**:
```
weather('rain', 12000) // Sets rain for 12000 ticks
```
```

--------------------------------

### get(container, address, ...)

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves a value from a container based on an address or path.

```APIDOC
## get(container, address, ...)

### Description
Returns the value at the specified address. For lists, it uses an index (supports negative numbers). For maps, it retrieves the value by key. For NBT, it uses the address as an NBT path.

### Parameters
- **container** (any) - Required - The list, map, or NBT object to query.
- **address** (any) - Required - The index, key, or NBT path to retrieve.

### Request Example
get([range(10)], 5) // Returns 5
get({'foo' -> 2}, 'foo') // Returns 2
```

--------------------------------

### System Information

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

Fetches system properties or a list of available properties.

```APIDOC
## `system_info()`, `system_info(property)`

### Description
Fetches the value of one of the following system properties. If called without arguments, it returns a list of available system_info options. It can be used to fetch various information, mostly not changing, or only available via low level system calls. In all circumstances, these are only provided as read-only.

##### Available options in the scarpet app space:
  * `app_name` - current app name or `null` if its a default app
  * `app_list` - list of all loaded apps excluding default commandline app
  * `app_scope` - scope of the global variables and function. Available options is `player` and `global`
  * `app_players` - returns a player list that have app run under them. For `global` apps, the list is always empty
 
##### Relevant world related properties
  * `world_name` - name of the world
  * `world_seed` - a numeric seed of the world
  * `world_dimensions` - a list of dimensions in the world
  * `world_path` - full path to the world saves folder
  * `world_folder` - name of the direct folder in the saves that holds world files
  * `world_carpet_rules` - returns all Carpet rules in a map form (`rule`->`value`). Note that the values are always returned as strings, so you can't do boolean comparisons directly. Includes rules from extensions with their namespace (`namespace:rule`->`value`). You can later listen to rule changes with the `on_carpet_rule_changes(rule, newValue)` event.
  * `world_gamerules` - returns all gamerules in a map form (`rule`->`value`). Like carpet rules, values are returned as strings, so you can use appropriate value conversions using `bool()` or `number()` to convert them to other values. Gamerules are read-only to discourage app programmers to mess up with the settings intentionally applied by server admins. Isn't that just super annoying when a datapack messes up with your gamerule settings? It is still possible to change them though using `run('gamerule ...`.
  * `world_spawn_point` - world spawn point in the overworld dimension
  * `world_time` - Returns dimension-specific tick counter.
  * `world_top` - Returns current dimensions' topmost Y value where one can place blocks.
  * `world_bottom` - Returns current dimensions' bottommost Y value where one can place blocks.
  * `world_center` - Returns coordinates of the center of the world with respect of the world border
  * `world_size` - Returns radius of world border for current dimension.
  * `world_max_size` - Returns maximum possible radius of world border for current dimension.
  * `world_min_spawning_light` - Returns minimum light level at which mobs can spawn for current dimension, taking into account datapacks

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Get Player Hunger Information

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves player hunger-related information. Returns `null` for non-players.

```javascript
query(e, 'hunger')
```

```javascript
query(e, 'saturation')
```

```javascript
query(e, 'exhaustion')
```

--------------------------------

### Get All Players in Dimension

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Returns all players in the caller's dimension. Use '*' for all players in the dimension.

```python
player(type = '*')
```

--------------------------------

### Create Screen

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Creates and opens a screen for a player. Supports various screen types and an optional callback for interaction handling.

```APIDOC
## create_screen(player, type, name, callback?)

### Description
Creates and opens a screen for a `player`. Available `type`s include `anvil`, `beacon`, `blast_furnace`, `brewing_stand`, `cartography_table`, `crafting`, `enchantment`, `furnace`, `generic_3x3`, `generic_9x1`, `generic_9x2`, `generic_9x3`, `generic_9x4`, `generic_9x5`, `generic_9x6`, `grindstone`, `hopper`, `lectern`, `loom`, `merchant`, `shulker_box`, `smithing`, `smoker`, `stonecutter`.

The `name` parameter can be formatted text displayed at the top of the screen (not shown in all screens).

An optional `callback` function `_(screen, player, action, data) -> ...` can be passed. The `action` can be `pickup`, `quick_move`, `swap`, `clone`, `throw`, `quick_craft`, `pickup_all`, `button`, `close`, `select_recipe`, or `slot_update`. `data` varies based on the action.

Returning `'cancel'` from the callback can cancel interactions (except `close`).

The function returns a `screen` value for use in inventory functions.

### Parameters
#### Path Parameters
- **player** (Player) - Required - The player to open the screen for.
- **type** (string) - Required - The type of screen to create (e.g., 'chest', 'crafting').
- **name** (FormattedText | string) - Optional - The name displayed at the top of the screen.
- **callback** (function) - Optional - A function to handle screen interactions.

### Request Example
```lua
local player = get_player()
local screen = create_screen(player, "generic_9x3", "My Custom Chest", function(screen, player, action, data)
    if action == "close" then
        print("Screen closed!")
    elseif action == "pickup" then
        print("Item picked up from slot: " .. data.slot)
    end
end)
```

### Response
#### Success Response (Screen Value)
- **screen** (Screen) - A value representing the created screen.
```

--------------------------------

### Create an anvil text prompt GUI

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Inventories.md

Implements an anvil screen to capture text input from a renamed paper item.

```scarpet
// anvil text prompt gui
__command() -> (
    global_screen = create_screen(player(),'anvil',format('r Enter a text'),_(screen, player, action, data)->(
        if(action == 'pickup' && data:'slot' == 2,
            renamed_item = inventory_get(screen,2);
            nbt = renamed_item:2;
            name = parse_nbt(nbt:'display':'Name'):'text';
            if(!name, return('cancel')); //don't accept empty string
            print(player,'Text: ' + name);
            close_screen(screen);
        );
        'cancel'
    ));
    inventory_set(global_screen,0,1,'paper','{display:{Name:\'{"text":""}\'}}');
);
```

--------------------------------

### Manage entity loading with entity_load_handler

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Examples of using entity_load_handler to modify or remove entities upon loading.

```scarpet
// veryfast method of getting rid of all the zombies. Callback is so early, its packets haven't reached yet the clients
// so to save on log errors, removal of mobs needs to be scheduled for later.
entity_load_handler('zombie', _(e, new) -> schedule(0, _(outer(e)) -> modify(e, 'remove')))

// another way to do it is to remove the entity when it starts ticking
entity_load_handler('zombie', _(e, new) -> entity_event(e, 'on_tick', _(e) -> modify(e, 'remove')))

// making all zombies immediately faster and less susceptible to friction of any sort
entity_load_handler('zombie', _(e, new) -> entity_event(e, 'on_tick', _(e) -> modify(e, 'motion', 1.2*e~'motion')))
```

--------------------------------

### Get Player Language

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Returns the player's language as a string. Returns `null` for non-player entities.

```javascript
query(e, 'language')
```

--------------------------------

### System Properties

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Auxiliary.md

JVM and system resource metrics.

```APIDOC
## System Properties

### Description
Provides metrics regarding JVM memory usage and CPU load.

### Properties
- **java_max_memory** (long) - Max memory accessible by JVM
- **java_allocated_memory** (long) - Currently allocated memory
- **java_used_memory** (long) - Currently used memory
- **java_cpu_count** (integer) - Number of processors
- **java_version** (string) - Java version
- **java_bits** (integer) - 32 or 64 bit
- **java_system_cpu_load** (float) - System CPU load percentage
- **java_process_cpu_load** (float) - JVM CPU load percentage
```

--------------------------------

### Library and App Downloading Configuration

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/Overview.md

Defines libraries or apps to be downloaded during app installation, specifying their source and optional target names.

```APIDOC
## 'libraries'

### Description
List of libraries or apps to be downloaded when installing the app from the app store. It needs to be a list of map-like resource descriptors.

### Library Descriptor Structure
```
{
    'source': 'URL | /absolute/path | relative/path',
    'target': 'new/app/name'
}
```

- **source**: Resource location. Must point to a scarpet app or library. Can be an arbitrary URL (starting with `http://` or `https://`), an absolute path in the app store (starting with `/`), or a relative path in the same folder as the app.
- **target**: Optional field indicating the new name of the app. If not specified, it will be placed in the main data folder with its original name.

**Note:** If the app has relative resource dependencies, Carpet will use the app's path for relatives if the app was loaded from the same app store, or none if loaded from an external URL. If you need to `import()` from dependencies, ensure `__config()` is called before any import referencing remote dependencies.
```

--------------------------------

### Get Player Walk Speed

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Returns a number indicating the player's movement speed while walking.

```javascript
query(e, 'walk_speed')
```

--------------------------------

### run(expr)

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Executes a vanilla Minecraft command and returns the result, output messages, and potential error messages.

```APIDOC
## run(expr)

### Description
Runs a vanilla command from the string result of the expression. Returns a triple containing the success count, a list of intercepted output messages, and an error message if the command failed.

### Parameters
#### Request Body
- **expr** (string) - Required - The command string to execute.

### Response
- **Returns** (triple) - [success_count, output_messages, error_message]. Returns null if the command was scheduled for later execution.
```

--------------------------------

### Get Player Fly Speed

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Returns a number indicating the player's movement speed while flying.

```javascript
query(e, 'fly_speed')
```

--------------------------------

### Configure Surface Lighting (1.18+ Mob Spawning)

Source: https://github.com/gnembon/fabric-carpet/wiki/How-to-spawn-proof-with-auto_light.sc

This snippet is for 1.18+ and optimizes surface lighting for mob spawning by checking for a block light level below 1. Adjust the value as needed.

```scarpet
                    && air(lpos) && block_light(lpos) < 1
```

--------------------------------

### Get Player Ping

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/Full.md

Retrieves the player's ping in milliseconds. Returns `null` if the entity is not a player.

```javascript
query(e, 'ping')
```

--------------------------------

### Get Block Opacity

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/BlocksAndWorldAccess.md

The `opacity(pos)` function returns the opacity level of the block at the given position.

```java
opacity(pos)
```

--------------------------------

### Retrieve and Evaluate Blocks

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/BlocksAndWorldAccess.md

Demonstrates block retrieval using the block function and the difference between lazy and eager evaluation.

```scarpet
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
```

```scarpet
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`
```

--------------------------------

### Get Biome List

Source: https://github.com/gnembon/fabric-carpet/blob/master/docs/scarpet/api/BlocksAndWorldAccess.md

Call `biome()` without arguments to retrieve a list of all biomes present in the world.

```java
biome()
```