### Install and Setup Sandstone CLI

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Installs the Sandstone CLI globally and demonstrates commands for creating, building, and watching Sandstone projects.

```bash
# Install the CLI globally
bun i -g sandstone-cli

# Create a new Sandstone project
sand create my-datapack

# Build the datapack
bun dev:build

# Build and watch for changes
bun dev:watch --verbose
```

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

### Install Smithed Libraries using Sand CLI

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/dependencies.md

Demonstrates how to install libraries from Smithed using the Sand CLI. This includes listing available libraries, installing specific ones like 'crafter', and managing installed libraries.

```bash
# Lists top 25 Smithed libraries to select ones to install.
sand i vanilla
sand add vanilla
sand install vanilla

# Installs the crafter library from Smithed
sand i vanilla crafter
sand add vanilla crafter
sand install vanilla crafter

# Lists all installed Smithed libraries to select ones to remove.
sand remove
sand uninstall

# Removes the crafter library
sand remove crafter
sand uninstall crafter
```

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

### Sandstone Command Examples

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Provides practical examples of Sandstone commands: giving items, applying effects, and granting advancements. These snippets illustrate direct command usage.

```ts
// Give 64 diamonds to all players
give('@a', 'minecraft:diamond', 64)

// Give Speed II to all players for 1 second
effect.give('@a', 'minecraft:speed', 1)

// Grant all advancements to all players
advancement.grant('@a').everything()
```

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

### Install Block Library using Package Managers

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/libraries/block.md

Installs the official Block Library using different package managers: Sand, Pnpm, and Npm. Choose the command that corresponds to your project's package manager.

```batch
sand install native block
```

```batch
pnpm i @sandstone-mc/block
```

```batch
npm i @sandstone-mc/block
```

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

### Sandstone Optional Arguments Example

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Demonstrates the usage of optional arguments in Sandstone commands, specifically for `effect.give`. It shows how to call the command with varying numbers of optional parameters.

```ts
MCFunction('optional_arguments', () => {
  // effect.give('@a') -> Invalid!
  effect.give('@a', 'minecraft:haste')
  effect.give('@a', 'minecraft:haste', 10)
  effect.give('@a', 'minecraft:haste', 10, 1)
  effect.give('@a', 'minecraft:haste', 10, 1, true)
})
```

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

### Sandstone Command Output Example

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Presents the resulting MCFunction code generated from the TypeScript command usage example.

```mcfunction
give @a minecraft:diamond 64
kill @e[type=zombie]
say Hello everyone!
effect give @a minecraft:speed 30 2
effect clear @a minecraft:poison
advancement grant @a everything
advancement revoke @s only minecraft:story/mine_stone
scoreboard objectives add deaths deathCount
scoreboard players set @s deaths 0
playsound minecraft:entity.experience_orb.pickup master @a
```

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

### Sandstone Execute Command Syntax

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Illustrates the Sandstone syntax for the `/execute` command, showing how to chain selectors and conditions before running a command. This example sets a dirt block under all players.

```ts
// Sets a block of dirt under all players
execute.as('@a').at('@s').run.setblock(rel(0, 0, 0), 'minecraft:dirt')
```

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

### Sandstone MCFunction Example

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

An example of defining an MCFunction in Sandstone, which encapsulates multiple commands. This function includes giving items, applying effects, and granting advancements.

```ts
MCFunction('example', () => {
  give('@a', 'minecraft:diamond', 64)
  effect.give('@a', 'minecraft:speed', 1)
  advancement.grant('@a').everything()
})
```

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

### Install Sandstone Native Libraries using pnpm

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/dependencies.md

Shows how to install and uninstall official Sandstone libraries, such as the 'block' library, using `pnpm`. These libraries are managed through the Sandstone library repository.

```bash
# Installs the official Block library from the Sandstone library repository
sand install native block
pnpm i @sandstone-mc/block

# Removes the library
pnpm uninstall @sandstone-mc/block
```

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

### Sandstone MCFunction Output Example

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Shows the generated MCFunction file content based on the TypeScript code provided.

```mcfunction
# default:hello
say Hello world!

# mydatapack:main
give @a minecraft:diamond 64

# default:caller
function default:helper
function default:helper
```

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

### Create Scoped BlockSets

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/libraries/block.md

Demonstrates creating BlockSets, which are scoped collections of blocks. This improves efficiency by reducing the scope of block conversions. Examples include using built-in tags, predefined lists, and dynamically loaded tags.

```typescript
// Uses a block group tag from vanilla, `wool`, scoping to only the 15 wool colors
const woolBlocks = BuiltinBlockSet('wool')

// Sets up a type-safe block set using a predefined list.
const spaceshipBlocks = new BlockSetClass(sandstonePack.core, [
  'cyan_terracotta',
  'glass',
  'sea_lantern',
  'iron_block',
  ...
] as const)

// Automatically loads in a block group tag
const barkBlocks = new BlockSetClass(sandstonePack.core, await (await fetch('https://raw.githubusercontent.com/Aeldrion/AESTD/master/data/aestd1/tags/blocks/wood_blocks.json')).json() as readonly string[])
```

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

### Sandstone: Using coordinate helpers in setblock commands

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/coordinates.md

Illustrates practical examples of using the `abs`, `rel`, and `loc` helper functions within Sandstone `setblock` commands. This covers scenarios with mixed coordinate types and multiple number inputs.

```typescript
// Compiles to /setblock 0 0 0 dirt
setblock(rel(0, 0, 0), 'dirt')

// Compiles to /setblock ^ ^ ^1 dirt
setblock(loc(0, 0, 1), 'dirt')

// Compiles to /setblock ~ 0 ~ bedrock
setblock([rel(0), abs(0), rel(0)], 'dirt')
```

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

### Define Custom Crafting Recipes with Sandstone

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Create custom crafting recipes with full typing for all recipe types using Sandstone. This includes examples for shaped crafting, shapeless crafting, smelting, stonecutting, and smithing recipes.

```typescript
import { Recipe } from 'sandstone'

// Shaped crafting recipe
Recipe('custom_sword', {
  type: 'crafting_shaped',
  pattern: [
    ' D ',
    ' D ',
    ' S '
  ],
  key: {
    'D': { item: 'minecraft:diamond' },
    'S': { item: 'minecraft:stick' }
  },
  result: {
    id: 'minecraft:diamond_sword',
    count: 1
  }
})

// Shapeless crafting recipe
Recipe('diamond_nuggets', {
  type: 'crafting_shapeless',
  ingredients: [
    { item: 'minecraft:diamond' }
  ],
  result: {
    id: 'minecraft:diamond',
    count: 9
  }
})

// Smelting recipe
Recipe('smelt_gravel', {
  type: 'smelting',
  ingredient: { item: 'minecraft:gravel' },
  result: { id: 'minecraft:flint' },
  experience: 0.1,
  cookingtime: 200
})

// Stonecutting recipe
Recipe('stone_bricks_from_stone', {
  type: 'stonecutting',
  ingredient: { item: 'minecraft:stone' },
  result: { id: 'minecraft:stone_bricks' },
  count: 1
})

// Smithing recipe
Recipe('netherite_upgrade', {
  type: 'smithing_transform',
  template: { item: 'minecraft:netherite_upgrade_smithing_template' },
  base: { item: 'minecraft:diamond_sword' },
  addition: { item: 'minecraft:netherite_ingot' },
  result: { id: 'minecraft:netherite_sword' }
})
```

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

### Implement Flow Control with If/Else Statements in Sandstone

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Shows how to use Sandstone's if/else statements, which compile to Minecraft's execute if/unless commands. Examples include simple 'if', chained 'if-else if-else', boolean logic combinations (AND, OR, NOT) using score comparisons and entity data checks, and conditional execution based on the block type at a specific location.

```typescript
import { _, MCFunction, say, give, kill, Objective, Selector, rel } from 'sandstone'

const score = Objective.create('score', 'dummy')

MCFunction('flow_demo', () => {
  const myScore = score('@s')

  // Simple if
  _.if(myScore.greaterThan(100), () => {
    say('High score!')
    give('@s', 'minecraft:diamond')
  })

  // If-else chain
  _.if(myScore.greaterOrEqualThan(100), () => {
    say('Legendary!')
  }).elseIf(myScore.greaterOrEqualThan(50), () => {
    say('Expert!')
  }).elseIf(myScore.greaterOrEqualThan(10), () => {
    say('Beginner!')
  }).else(() => {
    say('Noob!')
  })

  // Boolean logic
  const hasKills = myScore.greaterThan(0)
  const isAlive = _.data.entity('@s', 'Health')

  _.if(_.and(hasKills, isAlive), () => {
    say('Active player!')
  })

  _.if(_.or(myScore.equalTo(0), myScore.greaterThan(1000)), () => {
    say('Reset or prestige!')
  })

  _.if(_.not(hasKills), () => {
    say('Get your first kill!')
  })

  // Block conditions
  _.if(_.block(rel(0, -1, 0), 'minecraft:diamond_block'), () => {
    say('Standing on diamonds!')
  })
})
```

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

### ItemPredicate String Representation Examples in TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/itemPredicate.md

Illustrates how ItemPredicate objects are compiled into Minecraft's native item predicate syntax. This shows the direct translation of chained methods and logical operators into the game's format. Dependencies include 'sandstone'.

```typescript
import { ItemPredicate, NBT } from 'sandstone'

ItemPredicate('minecraft:diamond')
// → minecraft:diamond

ItemPredicate('minecraft:diamond_sword').has('minecraft:enchantments')
// → minecraft:diamond_sword[minecraft:enchantments]

ItemPredicate('*').without('minecraft:damage')
// → *[!minecraft:damage]

ItemPredicate('*').or(
  i => i.without('minecraft:damage'),
  i => i.exact('minecraft:damage', NBT.int(0))
)
// → *[!minecraft:damage|minecraft:damage=0]

ItemPredicate('#minecraft:swords')
  .has('minecraft:enchantments')
  .count({ min: 1 })
// → #minecraft:swords[minecraft:enchantments,count~{min:1}]
```

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

### Create Predicates for Conditional Logic with Sandstone

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Define predicates for conditional logic in advancements, loot tables, and commands using Sandstone. This example demonstrates creating weather, location, entity, and random chance predicates, and using them within MCFunction.

```typescript
import { Predicate, MCFunction, _, rel } from 'sandstone'

// Weather predicate
const isRaining = Predicate('is_raining', {
  condition: 'weather_check',
  raining: true
})

// Location predicate
const inNether = Predicate('in_nether', {
  condition: 'location_check',
  predicate: {
    dimension: 'minecraft:the_nether'
  }
})

// Entity predicate
const isOnFire = Predicate('is_on_fire', {
  condition: 'entity_properties',
  entity: 'this',
  predicate: {
    flags: { is_on_fire: true }
  }
})

// Random chance predicate
const luckyDrop = Predicate('lucky_drop', {
  condition: 'random_chance',
  chance: 0.1
})

MCFunction('predicate_demo', () => {
  // Use predicates in conditions
  _.if(isRaining, () => {
    say('It\'s raining!')
  })

  _.if(_.and(inNether, isOnFire), () => {
    say('Hot in here!')
  })
})
```

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

### Large Scale Flow Control in TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/if.md

This example illustrates a complex conditional structure using `_.if`, `elseIf`, and `else` for large-scale flow control. It includes nested loops and conditions, highlighting potential compile-time performance issues with deeply nested callbacks.

```typescript
const foo = Variable(0)

_.if(foo['<='](100000), () => {
  _.if(foo['<='](100), () => {
    for (let i = 0; i < 100; i++) {
      _.return.run(() => {
        _.if(foo['=='](i), () => {
          say(`${i}`)
        })
      })
    }
  }).elseIf(_.and(foo['>'](100), foo['<='](200)), () => {
    /// ...
  })
  /// ...
}).else(() => {
  /// ...
})
```

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

### Create Custom Advancements with Sandstone MC

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Explains how to define custom advancements in Sandstone MC, providing full typing for triggers and conditions. Includes examples for basic, conditional, multi-criteria advancements, and how to grant, revoke, and select players based on advancements.

```typescript
import { Advancement, MCFunction, Selector } from 'sandstone'

// Basic advancement
const firstKill = Advancement('first_kill', {
  display: {
    title: 'First Blood',
    description: 'Kill your first mob',
    icon: { id: 'minecraft:iron_sword' },
    frame: 'task'
  },
  criteria: {
    kill_mob: {
      trigger: 'minecraft:player_killed_entity'
    }
  }
})

// Advancement with specific conditions
const dragonSlayer = Advancement('dragon_slayer', {
  parent: 'minecraft:end/root',
  display: {
    title: 'Dragon Slayer',
    description: 'Defeat the Ender Dragon',
    icon: { id: 'minecraft:dragon_head' },
    frame: 'challenge',
    show_toast: true,
    announce_to_chat: true
  },
  criteria: {
    kill_dragon: {
      trigger: 'minecraft:player_killed_entity',
      conditions: {
        entity: { type: 'minecraft:ender_dragon' }
      }
    }
  },
  rewards: {
    experience: 1000
  }
})

// Multi-criteria advancement
const breeder = Advancement('animal_breeder', {
  display: {
    title: 'Animal Husbandry',
    description: 'Breed all farm animals',
    icon: { id: 'minecraft:wheat' },
    frame: 'goal'
  },
  criteria: {
    breed_cow: {
      trigger: 'minecraft:bred_animals',
      conditions: { child: { type: 'minecraft:cow' } }
    },
    breed_pig: {
      trigger: 'minecraft:bred_animals',
      conditions: { child: { type: 'minecraft:pig' } }
    },
    breed_sheep: {
      trigger: 'minecraft:bred_animals',
      conditions: { child: { type: 'minecraft:sheep' } }
    }
  }
})

MCFunction('advancement_demo', () => {
  // Grant/revoke methods
  dragonSlayer.grant('@a')
  dragonSlayer.revoke('@s')

  // Select players with advancement
  const slayers = Selector('@a', {
    advancements: { [dragonSlayer.name]: true }
  })
})
```

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

### Execute Single Commands in Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Demonstrates how to execute single commands using Sandstone's 'execute.as().run()' syntax. This is useful for performing actions on specific targets or all players.

```typescript
MCFunction('single_execute', () => {
  // Make a random player say Hello
  execute.as('@r').run.say('Hello!')
  // Put a block of dirt on a random player
  execute.as('@r').at('@s').run.setblock(rel(0, 0, 0), 'minecraft:dirt')
  // Summon a TNT on all players!
  execute.as('@a').at('@s').run.summon('minecraft:tnt', rel(0, 0, 0))
})
```

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

### Create and Set a Block Instance

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/libraries/block.md

Demonstrates how to create a block instance with specific properties and then set it in the world. This is a fundamental operation for manipulating blocks.

```typescript
const acaciaStairs = Block('acacia_stairs', '~ ~ ~', { facing: 'north', shape: 'straight' })

acaciaStairs.set()
```

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

### Try Block Conditional Check

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/libraries/block.md

A simple example demonstrating a conditional check using `_.block`. It checks if the block directly below the player is sandstone and sends a message if it is.

```typescript
MCFunction('tick', () => {
  // Execute as every player
  execute.as(Selector('@a')).at('@s').run(() => {
    // Detect sandstone under the player
    _.if(_.block(rel(0, -1, 0), 'sandstone'), () => {
      tellraw('@s', 'The framework is below your feet!')
    })
  })
}, { runEveryTick: true })
```

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

### Basic Command Usage in Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Demonstrates how to call Sandstone commands, distinguishing between commands with subcommands (accessed via properties) and commands with arguments (called as functions). It also highlights that a command is only written to the datapack when invoked.

```ts
// Example of a command with subcommands
effect.give('@a', 'minecraft:speed', 30, 2)
effect.clear('@a', 'minecraft:night_vision')

// Example of a command without subcommands
reload()
```

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

### Execute Commands with Sandstone API

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Demonstrates how to use Sandstone's fluent API to chain and execute Minecraft commands. Supports single commands, multiple commands via callbacks, and complex conditional executions. Requires 'sandstone' import.

```typescript
import { execute, setblock, say, summon, rel, Selector } from 'sandstone'

MCFunction('execute_demo', () => {
  // Single command execution
  execute.as('@a').at('@s').run.setblock(rel(0, -1, 0), 'minecraft:gold_block')

  // Execute as random player
  execute.as('@r').run.say('I was chosen!')

  // Multiple commands in one execute
  execute.as('@a').at('@s').run(() => {
    setblock(rel(0, -1, 0), 'minecraft:dirt')
    setblock(rel(0, 0, 0), 'minecraft:air')
    setblock(rel(0, 1, 0), 'minecraft:air')
  })

  // Complex execute chains
  execute
    .as('@e[type=villager]')
    .at('@s')
    .if.block(rel(0, -1, 0), 'minecraft:emerald_block')
    .run.summon('minecraft:iron_golem', rel(0, 1, 0))

  // Positioned execution
  execute.positioned(rel(0, 10, 0)).run.summon('minecraft:lightning_bolt')
})
```

```mcfunction
execute as @a at @s run setblock ~ ~-1 ~ minecraft:gold_block
execute as @r run say I was chosen!
execute as @a at @s run function default:execute_demo/execute_as
execute as @e[type=villager] at @s if block ~ ~-1 ~ minecraft:emerald_block run summon minecraft:iron_golem ~ ~1 ~
execute positioned ~ ~10 ~ run summon minecraft:lightning_bolt
```

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

### Build Sandstone Data Pack with Bun

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/getting-started/first-function.md

Builds the Sandstone data pack using the Bun runtime. The '--verbose' flag provides detailed output during the build process, useful for debugging.

```bash
bun dev:watch --verbose
```

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

### Build Sandstone Data Pack with Sand

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/getting-started/first-function.md

Builds the Sandstone data pack using the Sand command-line tool. The '--verbose' flag provides detailed output during the build process, useful for debugging.

```bash
sand watch --verbose
```

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

### Scoping Error Broadcasts with Sandstone Throw

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/return-throw.md

Explains how to scope the broadcast of a `throw` error to specific players using a selector. This allows error messages to be targeted, for example, only to administrators.

```typescript
_.throw('Failed to do necessary things!', Selector('@a', { tag: 'admin' }))
```

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

### Switch/Case on NBT Values in Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/switch-case.md

Illustrates how to use switch/case statements in Sandstone to conditionally execute logic based on the value of an NBT tag. This example checks the ID of an enchantment on an item.

```typescript
const item = Data('entity', '@s', 'Inventory[0].Enchantments[0].id')

_.switch(item, _
  .case('minecraft:sharpness', () => say('ouch!'))
  .case('minecraft:knockback', () => say('woah!'))
  .default(() => say('phew!'))
)
```

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

### Convert Between UUID String and Array Formats (TypeScript)

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/uuid.md

Provides examples of converting between the string representation of a UUID and its integer array format within Sandstone. This is useful for manipulating UUID data directly.

```typescript
import { UUID } from 'sandstone'

// From string to array
const uuid = UUID('f81d4fae-7dec-11d0-a765-00a0c91e6bf6')
console.log(uuid.known)  // [-123456789, 2111568922, -1818263473, 985609794]

// From array to string (only for known UUIDs)
const uuidString = uuid.arrayToString()  // 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
```

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

### Create Basic Selector - TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/selectors.md

Demonstrates the basic syntax for creating a Sandstone selector by providing the target and optional arguments. This is the foundation for all selector creation in Sandstone.

```typescript
import { Selector } from 'sandstone'

Selector('@a', { /** Arguments */ })
Selector('@e', { type: 'minecraft:cow', limit: 1, sort: 'random' })
```

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

### Sandstone Entity Data Condition

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/if.md

Illustrates checking for specific NBT data on an entity using Sandstone's `_.data` condition. This example detects if a player is holding a specific item (a stick).

```typescript
import { _, Selector, MCFunction, tellraw, execute } from 'sandstone'

MCFunction('tick', () => {
    execute.as(Selector('@a')).run(() => {
      _.if(_.data.entity('@s', 'SelectedItem{id:"minecraft:stick"}'), () => {
        tellraw('@s', 'Hey! Nice stick you got there.')
      })
    })
  },
  { runEveryTick: true }
)
```

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

### Define Damage Type with Flags (TypeScript)

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/damage_types.md

This example shows how to define a damage type and apply specific flags to modify its behavior. Sandstone automatically handles the necessary tag management for these flags.

```typescript
DamageType('damage_type_name', {
  message_id: 'name',

  exhaustion: 5,

  scaling: 'never',
}, {
  flags: ['no_knockback', 'bypasses_cooldown']
})
```

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

### Execute Multiple Commands in Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Illustrates how to execute multiple commands within a single 'run' block in Sandstone. This allows for sequential execution of commands under a specific context (e.g., 'as @a at @s').

```typescript
execute.as('@a').at('@s').run(() => {
  // All this commands are executed "as @a at @s".
  // Sets a block of dirt under all players, and air on their body & head.
  setblock('~ ~-1 ~', 'minecraft:dirt')
  setblock('~ ~ ~', 'minecraft:air')
  setblock('~ ~1 ~', 'minecraft:air')
})
```

```typescript
MCFunction('main', () => {
  execute.as('@a').at('@s').run(() => {
    // All this commands are executed "as @a at @s".
    // Sets a block of dirt under all players, and air on their body & head.
    setblock(rel(0, -1, 0), 'minecraft:dirt')
    setblock(rel(0,  0, 0), 'minecraft:air')
    setblock(rel(0, +1, 0), 'minecraft:air')
  })
})
```

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

### Sandstone For Loop: Range Iterator

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/loops.md

Iterates over a defined range of numbers. It takes a start and end value for the range and a callback function that receives the current number in the iteration. This is a concise way to loop through a sequence.

```typescript
_  .for([0, 10], 'iterate', i => {
    // Uses the score component in tellraw
    tellraw('@a', i)
  })
```

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

### Sandstone Block Data Condition

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/if.md

Demonstrates checking for NBT data on a block using Sandstone's `Data` condition. This example detects if a specific item (honey bottle) is present in the block below the player.

```typescript
import { _, Selector, MCFunction, tellraw, execute, rel, Data } from 'sandstone'

MCFunction('tick', () => {
    execute.as(Selector('@a')).at('@s').run(() => {
        _.if(Data('block', rel(0, -1, 0), 'Items[{id:"minecraft:honey_bottle"}]'), () => {
            tellraw('@s', 'There is some honey beneath you')
          }
        )
      })
  },
  { runEveryTick: true }
)
```

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

### Import Sandstone Commands

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/commands.md

Imports common commands from the Sandstone library. This is the initial step to use any Sandstone command.

```jsx
import { advancement, execute, kill, say, scoreboard } from 'sandstone'
```

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

### Create Separate Datapack with TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/custom.md

Defines a custom `PackType` for a separate datapack. This allows for custom output paths and handling of pack metadata. An example demonstrates creating a 'datapack-foo' and associating an MCFunction with it.

```typescript
import { PackType } from 'sandstone/pack/packType'

class DataPackFoo extends PackType {
  constructor() {
    super('datapack-foo', 'saves/$worldName$/datapacks/$packName$-foo', 'world/datapacks/$packName$-foo', 'datapacks/$packName$-foo', 'server', true, 'data', true)
  }

  handleOutput = async (type: 'output' | 'client' | 'server', readFile: handlerReadFile, writeFile: handlerWriteFile) => {
    if (type === 'output') {
      await writeFile('pack.mcmeta', JSON.stringify({
        pack_format: 21,
        description: 'Foo Pack',
      }))
    }
  }
}

const fooPack = sandstonePack.packTypes.set('datapack-foo', new DataPackFoo()).get('datapack-foo')!

MCFunction('bar', () => {
  say('bar')
}, {
  packType: fooPack,
})
```

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

### Initialize Global Score Variable in TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/dynamic.md

Illustrates the creation of a global score variable in Sandstone that is initialized to 0 upon datapack loading. This is useful for variables that need a default value from the start.

```typescript
// The number of entities will be set to 0 when the datapack loads
const numberOfEntities = Variable(0)
```

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

### Save and Load Entity References with UUIDs (TypeScript)

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/uuid.md

Shows a practical example of saving an entity's UUID to data storage and later loading it to reference that specific entity. It includes a selector fallback for robustness.

```typescript
import { MCFunction, UUID, Data, Selector, execute, tellraw } from 'sandstone'

// Storage for the saved UUID
const savedTarget = Data('storage', 'mypack:data', 'target_uuid')

MCFunction('save_target', () => {
  // Save the nearest pig's UUID to storage
  const target = UUID(Selector('@e', { type: 'minecraft:pig', limit: 1 }), {
    sources: { data: [savedTarget] }
  })
  tellraw('@s', 'Target saved!')
})

MCFunction('teleport_to_target', () => {
  // Load UUID from storage with a selector fallback for execute
  const target = UUID(savedTarget, {
    sources: { selector: Selector('@e', { type: 'minecraft:pig', limit: 1 }) }
  })
  // Execute at the entity's location and teleport @s there
  target.execute.at('@s').run.tp('@s', '~ ~ ~')
})
```

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

### Minimal Predicate Syntax in TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/predicates.md

Demonstrates the basic structure for creating a predicate in Sandstone using TypeScript. It requires importing the 'Predicate' class and defining a name and a condition.

```typescript
import { Predicate } from 'sandstone'

Predicate('predicate_name', {
  condition: '<condition type>',
  ...additionalProperties,
})
```

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

### Create and Use Labels with Sandstone (TypeScript)

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/labels.md

Demonstrates creating a label, tagging the current executor, removing tags, and using labels within selectors. This functionality relies on the Sandstone library.

```typescript
const sick = Label('sick')

// Tag current executor as sick
sick('@s').add()

// Current executor is healed!
sick('@s').remove()

// As nearest sick player
execute.as(sick('@p'))

// Whether there's a cow within 10 blocks that is sick
_.if(Selector('@e', { type: 'cow', limit: 1, tag: sick }), () => { ... })
```

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

### Complex Conditional Model with Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/item_model_definitions.md

This example showcases combining multiple conditions for intricate item model logic. It applies 'mypack:item/legendary_sword' to 'minecraft:diamond_sword' only if it is enchanted, has a custom name, and has no damage.

```typescript
import { ItemModelDefinition, ItemPredicate, NBT } from 'sandstone'

// Show special model only for enchanted, undamaged, named swords
ItemModelDefinition('minecraft:diamond_sword',
  ItemPredicate('minecraft:diamond_sword')
    .has('minecraft:enchantments')
    .has('minecraft:custom_name')
    .without('minecraft:damage')
    .model()
    .onTrue('mypack:item/legendary_sword')
    .onFalse('minecraft:item/diamond_sword')
)
```

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

### Create a Sandstone MCFunction

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/getting-started/first-function.md

Defines a new Minecraft function named 'hello' using Sandstone's MCFunction decorator. It includes a 'say' command to output 'Hello world!'. This is the core of creating custom functions in Sandstone.

```typescript
import { say, MCFunction } from 'sandstone';

MCFunction('hello', () => {
  say('Hello world!');
});
```

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

### NBT Integer and Long Array Syntax

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/nbt.md

Provides examples of how to represent NBT integer arrays (`I;`) and long arrays (`L;`) in Python. These are distinct from standard arrays of integers or longs and are used in specific Minecraft NBT structures.

```python
{ Test: [I; 0, 1, 2 ] } # Integer array
{ Test: [L; 0, 1, 2 ] } # Long array
```

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

### Create and Get Scoreboard Objectives with Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/objectives.md

Demonstrates how to create a new scoreboard objective that Sandstone will manage, or retrieve an existing one without creating it. This is useful for integrating with objectives already defined outside of Sandstone.

```typescript
import { Objective } from 'sandstone'

// Create a new objective named 'kills' of type 'playerKillCount'
const kills = Objective.create('kills', 'playerKillCount', [{text: 'Player Kills'}])

// Retrieve an existing objective named 'deaths' without creating it
// const deaths = Objective.get('deaths')
```

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

### Sandstone For Loop: Binary Iterator

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/loops.md

Iterates using a binary tree approach within a specified range. This can be more efficient for certain operations. It accepts a range (start, end, and optional maximum) and a callback function that receives the current value.

```typescript
_  .for([0, 10, 10], 'binary', i => {
    say(`${i}`)
  })
```

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

### Basic Function Macro Usage in Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/macros.md

Demonstrates the fundamental application of function macros within Sandstone. It shows how to define and use a macro to substitute values in commands, utilizing Sandstone's API for command generation.

```typescript
MCFunction('macro_test', () => {
  data.modify.storage('macro_test', 'Test').set.value(NBT({test:'5 10 37'}))
  functionCmd(MCFunction('using_macros', () => {
    raw('/tp @s $(test)')
  }), 'with', 'storage', 'macro_test', 'Test')
})
```

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

### Create Basic Item Predicates with Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/itemPredicate.md

Demonstrates creating simple item predicates using the `ItemPredicate` constructor in TypeScript. This includes matching specific items, items with certain components (like enchantments or damage), items with count constraints, and using item tags with negation.

```typescript
import { ItemPredicate, NBT } from 'sandstone'

// Simple item match
const diamondSword = ItemPredicate('minecraft:diamond_sword')

// Item with component tests
const enchantedSword = ItemPredicate('minecraft:diamond_sword')
  .has('minecraft:enchantments')
  .without('minecraft:damage')

// Any item with count constraint
const smallStack = ItemPredicate('*').count({ max: 16 })

// Tag with negation
const undamagedSword = ItemPredicate('#minecraft:swords').without('minecraft:damage')
```

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

### Sandstone If/Else Syntax

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/if.md

Demonstrates the basic syntax for if, else if, and else statements in Sandstone, mimicking classical programming language constructs. It shows how to chain multiple conditions.

```typescript
import { _ } from 'sandstone'

_.if(condition1, () => {
  say('Condition 1 is true')
})
  .elseIf(condition2, () => {
    say('Condition 2 is true')
  })
  .else(() => {
    say('Both condition 1 and condition 2 are false')
  })
```

```typescript
import { _ } from 'sandstone'

_.if(condition1, () => {
  say('I am a lonely if')
})

_.if(condition2, () => {
  say(2)
})
  .elseIf(condition3, () => {
    say(3)
  })
  .elseIf(condition4, () => {
    say(4)
  })
```

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

### Use Item Predicates with the Clear Command

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/itemPredicate.md

Provides examples of using `ItemPredicate` objects with the `clear` command in Sandstone (TypeScript) to remove specific items, items matching predicates, or items within quantity limits from player inventories.

```typescript
import { clear, ItemPredicate, NBT } from 'sandstone'

// Clear specific item
clear('@p', 'minecraft:dirt')

// Clear with predicate - remove enchanted swords
clear('@p', ItemPredicate('minecraft:diamond_sword').has('minecraft:enchantments'))

// Clear damaged tools
clear('@a', ItemPredicate('#minecraft:tools').has('minecraft:damage'))

// Clear with quantity limit - remove up to 64 cobblestone
clear('@p', ItemPredicate('minecraft:cobblestone'), 64)

// Clear any item with low durability
clear('@a', ItemPredicate('*').match('minecraft:damage', {
  durability: { max: NBT.int(10) }
}))
```

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

### Use Async/Await and Sleep in Sandstone MC

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Shows how to use async/await syntax for scheduling commands with delays in Sandstone MC. This enables creating dialogues with pauses, countdown timers, and delayed rewards.

```typescript
import { MCFunction, say, tellraw, sleep, give } from 'sandstone'

// Dialog with delays
MCFunction('dialog', async () => {
  tellraw('@a', '[NPC] Welcome, traveler!')
  await sleep('2s')

  tellraw('@a', '[NPC] I have a quest for you...')
  await sleep('3s')

  tellraw('@a', '[NPC] Defeat the dragon!')
  await sleep('1s')

  tellraw('@a', '[NPC] Here are some supplies.')
  give('@a', 'minecraft:diamond_sword')
})

// Countdown timer
MCFunction('countdown', async () => {
  say('Starting in 3...')
  await sleep('1s')

  say('2...')
  await sleep('1s')

  say('1...')
  await sleep('1s')

  say('GO!')
})

// Delayed reward
MCFunction('delayed_reward', async () => {
  say('You will receive your reward in 10 seconds!')
  await sleep('10s')
  give('@a', 'minecraft:diamond', 64)
  say('Reward delivered!')
})
```

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

### Compare Block Volumes

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/libraries/block.md

Compares two block volumes in the world. This involves specifying the area to compare, the corner with the lowest coordinates, and whether to ignore air blocks. The example compares a 3x3 area below the player with the area above them.

```typescript
import { _, Selector, MCFunction, tellraw, execute, rel } from 'sandstone'

MCFunction('tick', () => {
    // Execute as every player
    execute.as(Selector('@a')).at('@s').run(() => {
        // Detect sandstone under the player
        _.if(
          Blocks(
            // Area
            rel(-1, -1, -1),
            rel(1, -1, 1),
            // Corner
            rel(-1, 2, -1),
            // Scan Mode
            'all'
          ), () => {
            tellraw('@s', 'Above and below, it is all the same')
          }
        )
      })
  },
  { runEveryTick: true } 
)
```

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

### Build Sandstone Data Pack with pnpm

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/getting-started/first-function.md

Builds the Sandstone data pack using the pnpm package manager. The '--verbose' flag provides detailed output during the build process, useful for debugging.

```batch
pnpm dev:watch --verbose
```

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

### Returning and Executing Logic with Sandstone Return

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/return-throw.md

Illustrates returning a function that executes specific logic before returning a value. This allows for more complex actions to be performed when a condition is met, such as custom mob-specific behaviors.

```typescript
_.if(Selector('@s', { type: 'zombie' }), () => _.return.run(() => {
  // Do zombie stuff

  _.return(0)
}))

_.if(Selector('@s', { type: 'skeleton' }), () => _.return.run(() => {
  // Do skeleton stuff

  _.return(1)
}))

_.if(Selector('@s', { type: 'creeper' }), () => _.return.run(() => {
  // Do creeper stuff

  _.return(2)
}))
```

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

### Model Based on Custom Data (Weapon Tier) with Sandstone

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/item_model_definitions.md

This example demonstrates using custom data to differentiate item models. It assigns a 'legendary' model to 'minecraft:iron_sword' if its custom data matches '{ tier: 'legendary' }'.

```typescript
import { ItemModelDefinition, ItemPredicate } from 'sandstone'

// Different weapon tiers
ItemModelDefinition('minecraft:iron_sword',
  ItemPredicate('minecraft:iron_sword')
    .match('minecraft:custom_data', { tier: 'legendary' })
    .model()
    .onTrue('mypack:item/legendary_iron_sword')
    .onFalse('minecraft:item/iron_sword')
)
```

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

### Logical NOT Operation in TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/flow/if.md

The `_.not` operation negates a condition. It takes a single input and returns true if the input condition is false, and false if the input condition is true. This example demonstrates checking if a block is not a sandstone slab and the block below is not sandstone.

```typescript
const condA = _.block(rel(0, -1, 0), 'sandstone')
const condB = _.block(rel(0, 0, 0), 'sandstone_slab'); // Unspecified is equivalent to `~ ~ ~`
_.if(_.not(_.or(condA, condB)), () => {
  say('Not a jackpot :(')
})
```

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

### Create Raw Resource with TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/custom.md

Defines a raw resource, suitable for simple files like scarpet scripts or entity models. It takes a file path and content as arguments. The content can be a string or retrieved from an existing resource.

```typescript
RawResource('scripts/drop_heads.sc', `
// A Balanced way to get player heads in survival.

// stay loaded
__config() -> (
   m(
      l('stay_loaded','true')
   )
)

__on_player_dies(player) -> (
  if(rand(1) <= 0.3,
    xv = rand(0.5)-0.25
    yv = rand(0.5)
    zv = rand(0.5)-0.25

    motion = '[' + xv + 'd, ' + yv + 'd, ' + zv + 'd' + ']'
    data = '{Motion: ' + motion + ', Item: {id: "minecraft:player_head", Count:1b, tag:{SkullOwner: "' + player + '"}}}, PickupDelay: 3s'
    spawn('item', pos(player), data)
  )
)`)
```

```typescript
RawResource(resourcePack(), 'assets/minecraft/models/entity/pig.gecko.json', getExistingResource('entity_models/pig.gecko.json'))
```

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

### Practical Use Cases for Item Predicates in TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/variables/itemPredicate.md

Demonstrates practical applications of ItemPredicate, such as clearing damaged tools, checking for specific quest items, and removing non-stackable items from player inventories. Dependencies include 'sandstone'.

```typescript
import { clear, _, ItemPredicate, say, NBT } from 'sandstone'

// Clean up damaged tools from inventory
clear('@a', ItemPredicate('#minecraft:tools').match('minecraft:damage', {
  durability: { max: NBT.int(5) }
}))

// Check if player has required quest item
_.if(
  _.items.entity('@s', 'inventory.*',
    ItemPredicate('minecraft:diamond').match('minecraft:custom_data', {
      quest_id: 'main_quest_1'
    })
  ),
  () => {
    say('Quest item found!')
  }
)

// Remove all non-stackable items
clear('@a', ItemPredicate('*')
  .exact('minecraft:max_stack_size', NBT.int(1))
)
```

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

### Define a Minimal Sandstone Recipe (TypeScript)

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/recipes.md

This snippet shows the basic structure for creating a custom recipe in Sandstone. It requires importing the 'Recipe' class and defining the recipe's name, type, and result. The 'result' can be a simple item name or an object specifying the item and quantity.

```typescript
import { Recipe } from 'sandstone'

Recipe('recipe_name', {
  type: '<type>',
  result: '<item>' /* or */ { item: '<item>' },
})
```

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

### Create MCFunction Files with Sandstone

Source: https://context7.com/sandstone-mc/sandstone-documentation/llms.txt

Demonstrates how to create Minecraft function files using the MCFunction API in Sandstone. It covers basic functions, namespaced functions, and functions with specific run conditions like load, tick, or intervals.

```typescript
import { MCFunction, say, give, tellraw } from 'sandstone'

// Basic function in default namespace
MCFunction('hello', () => {
  say('Hello world!')
})

// Function with namespace
MCFunction('mydatapack:main', () => {
  give('@a', 'minecraft:diamond', 64)
})

// Function that runs on datapack load
MCFunction('setup', () => {
  say('Datapack loaded!')
}, { runOnLoad: true })

// Function that runs every tick
MCFunction('tick', () => {
  // Commands run every game tick
}, { runEveryTick: true })

// Function that runs every second
MCFunction('periodic', () => {
  say('One second passed!')
}, { runEvery: '1s' })

// Lazy function - only created if called
const helper = MCFunction('helper', () => {
  say('Helper called!')
}, { lazy: true })

// Calling another function
MCFunction('caller', () => {
  helper()
  helper()
})
```

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

### Define Custom Pack Type for Mod Configuration with TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/resources/custom.md

Creates a custom `PackType` for managing mod configurations. This example defines a 'mod-config' pack type with a specific output structure. It then uses `RawResource` to place a configuration file within this custom pack.

```typescript
import { PackType } from 'sandstone/pack/packType'

class ModConfig extends PackType {
  constructor() {
    super('mod-config', 'config', 'config', 'config', 'both')
  }
}

export const modConfig = new ModConfig()

sandstonePack.packTypes.set('mod-config', )

RawResource(modConfig, 'techy_haven/main.cfg', `
foo=bar
baz=21
`)
```

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

### Use Selectors in Commands - TypeScript

Source: https://github.com/sandstone-mc/sandstone-documentation/blob/master/docs/features/selectors.md

Shows how to assign selectors to variables and use them as arguments for Sandstone commands like 'kill' and 'give'. This illustrates practical application of created selectors.

```typescript
// Kill all cows
const cows = Selector('@e', { type: 'minecraft:cow' })
kill(cows)

// Give 32 diamonds to winners
const winners = Selector('@e', { tag: 'winner' })
give(winners, 'minecraft:diamond', 32)
```