Stonecutter

https://stonecutter.kikugie.dev/wiki
Admin
Stonecutter is a Gradle plugin designed for developing and maintaining Minecraft mods across...
Tokens:26,939
Snippets:357
Trust Score:5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Fabric Configuration Example

Source: https://stonecutter.kikugie.dev/wiki/start/builds

Full example of a version-aware build script for a Fabric project.

```kotlin
plugins {
    id("net.fabricmc.fabric-loom-remap") version "1.14-SNAPSHOT"
}

// These lines make the mod filename `{mod.id}-${mod.version}+${sc.current.version}.jar`
version = "${property("mod.version")}+${sc.current.version}"
base.archivesName = property("mod.id") as String

val requiredJava = when {
    sc.current.parsed >= "1.20.6" -> JavaVersion.VERSION_21
    sc.current.parsed >= "1.18" -> JavaVersion.VERSION_17
    sc.current.parsed >= "1.17" -> JavaVersion.VERSION_16
    else -> JavaVersion.VERSION_1_8
}

dependencies {
    minecraft("com.mojang:minecraft:${sc.current.version}")
    mappings(loom.officialMojangMappings())
    
    modImplementation("net.fabricmc:fabric-loader:${property("deps.fabric_loader")}")
}

java {
    withSourcesJar()
    targetCompatibility = requiredJava
    sourceCompatibility = requiredJava
}
```

```groovy
plugins {
    id 'net.fabricmc.fabric-loom-remap' version '1.14-SNAPSHOT'
}
```

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

### Flattening mode output examples

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

Text output examples for JOIN and LINES flattening modes.

```text
This is my new mod! Hope you like it :)
```

```text
This is my new mod! 
Hope you like it :)
```

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

### Define root properties

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Example content for a root gradle.properties file.

```properties
deps.fabric_loader=...
```

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

### Define Project Configuration

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Examples of configuring project versions and build scripts in TOML.

```toml
# Same as just "1.21.1"
project = "1.21.1"
```

```toml
# Same as "1.21.1-fabric:1.21.1"
project = "1.21.1-fabric"
version = "1.21.1"
```

```toml
# Same as "1.21.1::custom-build.gradle.kts"
project = "1.21.1"
buildscript = "custom-build.gradle.kts"
```

```toml
# Same as "1.21.1-fabric:1.21.1:custom-build.gradle.kts"
project = "1.21.1-fabric"
version = "1.21.1"
buildscript = "custom-build.gradle.kts"
```

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

### Comment Range Example

Source: https://stonecutter.kikugie.dev/wiki/config/handlers

Demonstrates the expected linear ordering of comment start and end tokens.

```java
/* comment */ */
//            ^ Not `comment end`, because it's not in a comment
```

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

### Property File Formats

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Examples of property definitions in different file formats.

```toml
mod.id = "example"
mod.version = "0.1"

["1.21.1"]
deps.example = "1.0.0"
```

```yaml
mod:
  id: "example"
  version: "0.1"
"1.21.1":
  deps:
    example: "1.0.0"
```

```json
{
  "mod": {
    "id": "example",
    "version": "0.1"
  },
  "1.21.1": {
    "deps:example": "1.0.0"
  }
}
```

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

### Example Java Entrypoint Versions

Source: https://stonecutter.kikugie.dev/wiki/config/params

Java source code variants demonstrating package changes after version-based string replacement.

```java
import io.github.me.MyEntrypoint;
import io.github.me.data.Version;

public void example() {
    MyEntryPoint.verifyVersion(Version.LATEST);
}
```

```java
import dev.me.MyEntrypoint;
import dev.me.data.Version;

public void example() {
    MyEntryPoint.verifyVersion(Version.LATEST);
}
```

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

### Abstract Syntax Tree Structure Example

Source: https://stonecutter.kikugie.dev/wiki/config/params

Demonstrates a typical tree-like structure for conditions and functions in Java.

```java
void example() {
    if (condition1) {
        action1();
        action2();
    }
    
    if (condition2)
        singleAction();
}
```

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

### Example Java Code Before and After Replacement

Source: https://stonecutter.kikugie.dev/wiki/config/params

Demonstrates the effect of string replacements on Java source code.

```java
void example(ResourceLocation identifier) {
   var parameter = ResourceLocationParameter.of(identifier);
}
```

```java
void example(Identifier identifier) {
   var parameter = ResourceLocationParameter.of(identifier);
}
```

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

### YAML language file format

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

Example of a language file written in YAML.

```yaml
modid:
  item:
    foo: "Foo Item"
    bar: "Bar Item"
  block:
    foo: "Foo Block"
    bar: "Bar Block"
```

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

### TOML language file format

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

Example of a language file written in TOML.

```toml
[modid.item]
foo = "Foo Item"
bar = "Bar Item"

[modid.block]
foo = "Foo Block"
bar = "Bar Block"
```

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

### Configure Multi-loader Tags

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Manually adding version and loader tags for multi-loader project setups.

```kotlin
stonecutter {
    val (version, loader) = current.project.split('-', limit = 2)
    properties.tags(version, loader)
}
```

```groovy
stonecutter {
    def (version, loader) = current.project.split('-', 2)
    properties.tags(version, loader)
}
```

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

### Manual Mod Dependency Setup

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/dependencies

Standard Gradle configuration for adding a mod dependency using manual Maven coordinates.

```kotlin
repositories {
    maven("https://cursemaven.com") { name = "Curseforge" }
}

dependencies {
    modImplementation("curse.maven:lithium-360438:6713689")
}
```

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

### Demonstrate Replacement Ordering Issues

Source: https://stonecutter.kikugie.dev/wiki/config/params

Example of overlapping string replacements that may lead to leftover values during version switches.

```kotlin
stonecutter {
    replacements.string(current.parsed < "1.21") {
        replace("A", "B")
    }

    replacements.string(current.parsed < "1.20") {
        replace("B", "C")
    }
}
```

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

### Defining Structured Properties

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Examples of defining project properties using different structured data formats.

```toml
mod.id = "example-mod"
mod.title = "Example"
mod.version = "1.0.0"

[fabric]
fabric_loader = "0.18.4"

[fabric."1.21.1"]
fabric_api = "0.116.8+1.21.1"

[fabric."1.21.11"]
fabric_api = "0.141.3+1.21.11"

[neoforge."1.21.1"]
neoforge_loader = "21.1.219"

[neoforge."1.21.11"]
neoforge_loader = "21.11.38-beta"
```

```yaml
mod:
  id: "example-mod"
  title: "Example"
  version: "1.0.0"

fabric:
  fabric_loader: "0.18.4"
  "1.21.1":
    fabric_api: "0.116.8+1.21.1"
  "1.21.11":
    fabric_api: "0.141.3+1.21.11"

neoforge:
  "1.21.1":
    neoforge_loader: "21.1.219"
  "1.21.11":
    neoforge_loader: "21.1.219"
```

```json
{
  "mod": {
    "id": "example-mod",
    "title": "Example",
    "version": "1.0.0"
  },

  "fabric": {
    "fabric_loader": "0.18.4",
    "1.21.1:fabric_api": "0.116.8+1.21.1",
    "1.21.11:fabric_api": "0.141.3+1.21.11"
  },

  "neoforge": {
    "1.21.1:neoforge_loader": "21.1.219",
    "1.21.11:neoforge_loader": "21.11.38-beta"
  }
}
```

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

### List flattening example

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

A JSON file containing a list for rich text support.

```json
{
  "modid.description": [
    "This is my new mod! ",
    "Hope you like it :)"
  ]
}
```

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

### Define Property

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Example of defining a property that overwrites existing values.

```text
my_property = "World"
```

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

### Fletching Table Dependency Setup

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/dependencies

Recommended repository configuration and usage of Fletching Table functions to resolve mod dependencies.

```kotlin
repositories {
    // The recommended way of setting up Modrinth/Curseforge mavens
    fun strictMaven(url: String, alias: String, vararg groups: String) = exclusiveContent {
        forRepository { maven(url) { name = alias } }
        filter { groups.forEach(::includeGroup) }
    }
    strictMaven("https://www.cursemaven.com", "Curseforge", "curse.maven")
    strictMaven("https://api.modrinth.com/maven", "Modrinth", "maven.modrinth")
}

dependencies {
    modImplementation(fletchingTable.modrinth("lithium", "1.21.7"))
    // or
    modImplementation(fletchingTable.curseforge("lithium", "1.21.7"))
}
```

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

### Structured Property Data

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Example of structured data representation in different formats.

```toml
["1.21.1"]
mod.supported_versions = ["1.21", "1.21.1", "1.21.2"]
```

```yaml
"1.21.1":
  mod:
    supported_versions:
      - "1.21"
      - "1.21.1"
      - "1.21.2"
```

```json
{
  "1.21.1": {
    "mod:supported_versions": [
      "1.21", 
      "1.21.1",
      "1.21.2"
    ]
  }
}
```

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

### Define JSON structure for dependency injection

Source: https://stonecutter.kikugie.dev/wiki/tips/resource-processing

Example structure for a fabric.mod.json file prepared for template substitution.

```json
{
  // other properties
  "requires": {
    "fabric": ">=0.16",
    "minecraft": "${minecraft}",
    // inject dependencies here
  },
}
```

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

### Access Widener to Access Transformer conversion

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/accessconverters

Example of an Access Widener file and its corresponding converted Access Transformer configuration.

```access
accessWidener v2 named

accessible method com/mojang/blaze3d/platform/NativeImage writeToChannel (Ljava/nio/channels/WritableByteChannel;)Z
```

```access
public com.mojang.blaze3d.platform.NativeImage
public com.mojang.blaze3d.platform.NativeImage writeToChannel(Ljava/nio/channels/WritableByteChannel;)Z
```

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

### Stonecutter manifest metadata format

Source: https://stonecutter.kikugie.dev/wiki/config/controller

Example of the metadata properties stored in the JAR manifest file.

```text
Stonecutter-Plugin-Version: ${dev.kikugie.stonecutter.StonecutterPlugin.VERSION}
Stonecutter-Gradle-Version: ${project.gradle.gradleVersion}
Stonecutter-Node-Project: ${sc.current.project}
Stonecutter-Node-Version: ${sc.current.version}
```

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

### String Literal Example

Source: https://stonecutter.kikugie.dev/wiki/config/handlers

Example of a string literal that causes naive scanners to incorrectly identify comments.

```properties
property="this # should not be a comment!"
```

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

### Select and expand access transformer files in build scripts

Source: https://stonecutter.kikugie.dev/wiki/tips/resource-processing

Select the appropriate configuration file based on the version and update the neoforge.mods.toml template.

```kotlin
val minecraft = stonecutter.current.version
val accesstransformer = when {
    stonecutter.eval(minecraft, ">=1.21") -> "1.21.cfg"
    stonecutter.eval(minecraft, ">=1.20") -> "1.20.cfg"
    else -> "1.19.cfg"
}

minecraft {
    accessTransformers {
        file("../../src/main/resources/accesstransformers/$accesstransformer")
    }
}

tasks.processResources {
    filesMatching("META-INF/neoforge.mods.toml") {
        expand(mapOf(
            // other properties
            "at_file" to accesstransformer,
        ))
    }
}
```

```groovy
def minecraft = stonecutter.current.version
def accesstransformer = stonecutter.eval(minecraft, ">=1.21") ? "1.21.cfg" 
    : stonecutter.eval(minecraft, ">=1.20") ? "1.20.cfg" 
    : "1.19.cfg"

minecraft {
    accessTransformers {
        file("../../src/main/resources/accesstransformers/$accesstransformer")
    }
}

processResources {
    filesMatching("META-INF/neoforge.mods.toml") {
        expand([
            // other properties
            at_file: accesstransformer,
        ])
    }
}
```

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

### Configure Versions First

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Defines project versions and their associated branches using different configuration formats.

```json
{
  "$schema": "https://stonecutter.kikugie.dev/settings-schema/latest.json",
  "vcs": "1.21.1", // Optional
  "versions": {
    "1.20.1": ["", "fabric", "forge"],
    "1.21.1": ["", "fabric", "neoforge"]
  }
}
```

```toml
"$schema" = "https://stonecutter.kikugie.dev/settings-schema/latest.json"
vcs = "1.21.1"  # Optional

[versions]
"1.20.1" = ["", "fabric", "forge"]
"1.21.1" = ["", "fabric", "neoforge"]
```

```yaml
$schema: "https://stonecutter.kikugie.dev/settings-schema/latest.json"
vcs: "1.21.1"  # Optional

versions:
  "1.20.1":
    - ""
    - "fabric"
    - "forge"
  "1.21.1":
    - ""
    - "fabric"
    - "neoforge"
```

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

### Configure output file style

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

Enabling key sorting and pretty printing for output files.

```kotlin
fletchingTable {
    lang.all {
        // Enables key sorting by their dot-separated segments
        sortKeys = true
        
        // Places converted language entries on separate lines
        prettyPrint = true
    }
}
```

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

### Data-driven configuration

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Define project structure using external data files.

```json5
{
  "$schema": "https://stonecutter.kikugie.dev/settings-schema/latest.json",
  "vcs": "1.21.1-fabric", // Optional
  "versions": [
    "1.20.1-fabric:1.20.1",
    "1.21.1-fabric:1.21.1",
    "1.20.1-forge:1.20.1:forge-build.gradle.kts",
    "1.21.1-neoforge:1.21.1:neoforge-build.gradle.kts"
  ]
}
```

```toml
"$schema" = "https://stonecutter.kikugie.dev/settings-schema/latest.json"
vcs = "1.21.1-fabric" # Optional

[[versions]]
project = "1.20.1-fabric"
version = "1.20.1"

[[versions]]
project = "1.21.1-fabric"
version = "1.21.1"

[[versions]]
project = "1.20.1-forge"
version = "1.20.1"
buildscript = "forge-build.gradle.kts"

[[versions]]
project = "1.21.1-neoforge"
version = "1.21.1"
buildscript = "neoforge-build.gradle.kts"
```

```yaml
$schema: "https://stonecutter.kikugie.dev/settings-schema/latest.json"
vcs: "1.21.1-fabric" # Optional

versions:
  - project: "1.20.1-fabric"
    version: "1.20.1"
  - project: "1.21.1-fabric"
    version: "1.21.1"
  - project: "1.20.1-forge"
    version: "1.20.1"
    buildscript: "forge-build.gradle.kts"
  - project: "1.21.1-neoforge"
    version: "1.21.1"
    buildscript: "neoforge-build.gradle.kts"
```

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

### Conditional version evaluation

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Example of a conditional check that may be affected by semantic versioning rules.

```java
//? if >=1.20.1
```

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

### Configure Branches First

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Defines project branches and their associated versions using different configuration formats.

```json
{
  "$schema": "https://stonecutter.kikugie.dev/settings-schema/latest.json",
  "vcs": "1.21.1", // Optional
  "branches": {
    "": ["1.20.1", "1.21.1"]
    "fabric": ["1.20.1", "1.21.1"]
    "forge": ["1.20.1"]
    "neoforge": ["1.21.1"]
  }
}
```

```toml
"$schema" = "https://stonecutter.kikugie.dev/settings-schema/latest.json"
vcs = "1.21.1" # Optional

[branches]
"" = ["1.20.1", "1.21.1"]
fabric = ["1.20.1", "1.21.1"]
forge = ["1.20.1"]
neoforge = ["1.21.1"]
```

```yaml
$schema: "https://stonecutter.kikugie.dev/settings-schema/latest.json"
vcs: "1.21.1" # Optional

branches:
  "": 
    - "1.20.1"
    - "1.21.1"
  fabric: 
    - "1.20.1"
    - "1.21.1"
  forge: 
    - "1.20.1"
  neoforge: 
    - "1.21.1"
```

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

### Version Type Comparison

Source: https://stonecutter.kikugie.dev/wiki/config/params

Demonstrates parsing and comparison of semantic and string-based versions in Kotlin.

```kotlin
val semantic: SemanticVersion = SemanticVersion.parse("1.0")
val string: StringVersion = StringVersion.parse("release")

assert(semantic < string) // Provided by `Comparable<Version>`
assert(semantic.value < string.value) // "1.0" < "release"
```

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

### Invalid fabric.mod.json structure

Source: https://stonecutter.kikugie.dev/wiki/tips/interface-injection

Example of an unsupported JSON structure that fails validation due to placeholders and comments.

```json5
{
  "schemaVersion": 1,
  "id": "${id}",
  "version": "${version}",
  // ... | this is unsupported
  ${injected_entry} 
}
```

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

### Demonstrate Ambiguous Replacements

Source: https://stonecutter.kikugie.dev/wiki/config/params

Configuration that fails due to conflicting replacement targets for the same version range.

```kotlin
stonecutter {
    replacements.string(current.parsed >= "1.21") {
        replace("A", "B")
    }

    replacements.string(current.parsed >= "1.20") {
        replace("B", "C")
    }
}
```

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

### Conditional access converter registration

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/accessconverters

Example of restricting access converter registration to Forge or NeoForge loaders in a multi-loader project.

```kotlin
fletchingTable {
    if (isForge || isNeoForge) accessConverter.register //...
}
```

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

### Define Project Notation

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Syntax for declaring projects using compact notation.

```text
project(:(version)(:buildscript))
```

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

### Compressing Property Paths

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Use colons to join keys and compress property paths in configuration files.

```toml
"extras:my_property" = "Hello"

[extras]
```

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

### Configure Repository in settings.gradle.kts

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/setup

Add the KikuGie Snapshots repository to the plugin management block.

```kotlin
pluginManagement {
    repositories {
        maven("https://maven.kikugie.dev/snapshots") { name = "KikuGie Snapshots" }
    }
}
```

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

### Process AccessTransformer Files

Source: https://stonecutter.kikugie.dev/wiki/config/build

Use sc.process to generate a versioned variant of an AccessTransformer file for NeoForge projects.

```kotlin
neoForge {
    // Input in the shared `src/` directory; output in `versions/.../build/`
    val atFile = rootProject.file("src/main/resources/META-INF/accesstransformer.cfg")
    accessTransformers.from(sc.process(atFile, "build/processed.cfg"))
}
```

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

### Register Branches and Versions

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Define versions and branches within a tree to manage shared source directories.

```kotlin
stonecutter.create(rootProject) {
    versions("1.20.1", "1.21.1")
    branch("api") // Inherits versions above
}
```

```groovy
stonecutter.create getRootProject() {
    versions "1.20.1", "1.21.1"
    branch "api" // Inherits versions above
}
```

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

### Define String Replacements in Gradle

Source: https://stonecutter.kikugie.dev/wiki/config/params

Configures string replacements for specific versions. Includes an example of preventing a replacement by mapping a value to itself.

```kotlin
stonecutter {
    replacements.string(current.parsed >= "1.21.11") {
        replace("ResourceLocation", "Identifier")
        replace("ResourceLocationParameter", "ResourceLocationParameter")
    }
}
```

```groovy
stonecutter {
    replacements.string(current.parsed.matches '>=1.21') {
       replace 'ResourceLocation', 'Identifier'
       replace 'ResourceLocationParameter', 'ResourceLocationParameter'
    }
}
```

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

### Define Project Nodes with Snapshots

Source: https://stonecutter.kikugie.dev/wiki/start/settings

Registering multiple versions including specific snapshots or release candidates.

```kotlin
stonecutter {
    create(rootProject) {
        versions("1.20.1", "1.21.1", "1.21.4")
        version("1.21.11-snapshot", "1.21.11-rc2") 
    }
}
```

```groovy
stonecutter {
    create(getRootProject()) {
        versions "1.20.1", "1.21.1", "1.21.4"
        version "1.21.11-snapshot", "1.21.11-rc2"
    }
}
```

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

### Define Dependencies in Build Scripts

Source: https://stonecutter.kikugie.dev/wiki/config/params

Configure project dependencies using snake_case names in build.gradle.kts or build.gradle files.

```kotlin
stonecutter {
    dependencies["mod_menu"] = property("mod_menu_version") as String
    
    // Dependencies have the same kinds of assignment functions as constants
}
```

```groovy
stonecutter {
    dependencies['mod_menu'] = project.mod_menu_version.toString()

    // Dependencies have the same kinds of assignment functions as constants
}
```

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

### Define Swaps in Build Scripts

Source: https://stonecutter.kikugie.dev/wiki/config/params

Define reusable string swaps in build scripts to reduce boilerplate code.

```kotlin
stonecutter {
    swaps["my_swap"] = when {
        eval(current.version, "<1.21") -> "method1();"
        else -> "method2();"
    }
    
    // Swaps have the same kinds of assignment functions as constants
}
```

```groovy
stonecutter {
    swaps['my_swap'] = eval(current.version, '<1.21')
            ? 'method1();'
            : 'method2();'
    
    // Swaps have the same kinds of assignment functions as constants
}
```

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

### Demonstrate Cyclical Replacements

Source: https://stonecutter.kikugie.dev/wiki/config/params

Configuration that fails due to circular dependencies between replacement values.

```kotlin
stonecutter {
    replacements.string(current.parsed >= "1.21") {
        replace("A", "B")
    }

    replacements.string(current.parsed >= "1.20") {
        replace("B", "A")
    }
}
```

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

### Inherit Configuration

Source: https://stonecutter.kikugie.dev/wiki/config/handlers

Reuses an existing file handler configuration for a new file extension.

```kotlin
stonecutter handlers {
    // Copy the Java configuration to HJson
    inherit("java", "hjson")
}
```

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

### Set active version via file

Source: https://stonecutter.kikugie.dev/wiki/config/controller

Assign the active version by reading the string from a specified file.

```kotlin
stonecutter active file("active.txt")
```

```groovy
stonecutter.active file("active.txt")
```

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

### Configure KSP plugins

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/entrypoints

Add the Kotlin JVM and KSP plugins to the build script before the Fletching Table plugin.

```kotlin
kotlin("jvm") version "2.2.10"
id("com.google.devtools.ksp") version "2.2.10-2.0.2"
```

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

### Exclude Files with Multiple Patterns

Source: https://stonecutter.kikugie.dev/wiki/config/handlers

Demonstrates multiple exclusion patterns for source set directories.

```kotlin
stonecutter {
    filters.exclude("src/main/java/com/example/BadClass.java") 
    filters.exclude("java/com/example/BadClass.java") 
}
```

```groovy
stonecutter {
    filters.exclude 'src/main/java/com/example/BadClass.java'
    filters.exclude 'java/com/example/BadClass.java'
}
```

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

### Register language file patterns

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

Registering directories for language file processing in build.gradle.kts.

```kotlin
fletchingTable {
    lang.create("main") {
        // Each file in this directory will be processed and renamed to {filename}.json
        patterns.add("assets/modid/lang/**")
    }
}
```

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

### Define Swaps with Parameters

Source: https://stonecutter.kikugie.dev/wiki/config/params

Use parameters in swaps to dynamically fill templates.

```kotlin
stonecutter {
    swaps["my_swap"] = when {
        current.parsed >= "1.21" -> "method1($1, $2);"
        else -> "method2($2, $1);"
    }
}
```

```groovy
stonecutter {
    swaps['my_swap'] = current.parsed.matches('>=1.21')
        ? 'method1($1, $2);'
        : 'method2($2, $1);'
}
```

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

### Naive Commenter Implementation

Source: https://stonecutter.kikugie.dev/wiki/config/handlers

A simple implementation that prefixes every line with a hash symbol, noting that it ignores indentation and may double-comment existing lines.

```kotlin
comment { scope: String ->
    scope.lines().joinToString("\n") { "#$it" }
}
```

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

### Configure shared parameters

Source: https://stonecutter.kikugie.dev/wiki/config/controller

Use the parameters block to configure file processor parameters. This is preferred over subprojects for lazy evaluation.

```kotlin
stonecutter parameters {
    swaps["minecraft"] = "\"${current.version}\";"
    dependencies["fapi"] = node.project.property("deps.fabric_api") as String
}
```

```groovy
stonecutter.parameters {
    swaps.put 'minecraft', "\"${current.version}\";"
    dependencies.put 'fapi', node.project.property('deps.fabric_api').toString()
}
```

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

### Process AccessWidener Files

Source: https://stonecutter.kikugie.dev/wiki/config/build

Use sc.process to generate a versioned variant of an AccessWidener file for Fabric projects.

```kotlin
loom {
    // Input in the shared `src/` directory; output in `versions/.../build/`
    val awFile = rootProject.file("src/main/resources/modid.aw")
    accessWidenerPath = sc.process(awFile, "build/processed.aw")
}
```

```groovy
loom {
    // Input in the shared `src/` directory; output in `versions/.../build/`
    def awFile = rootProject.file 'src/main/resources/modid.aw'
    accessWidenerPath = sc.process awFile, 'build/processed.aw'
}
```

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

### Configure AccessTransformer in NeoForge

Source: https://stonecutter.kikugie.dev/wiki/config/build

Processes an access transformer configuration file from the source directory and outputs it to the build directory.

```groovy
neoForge {
    // Input in the shared `src/` directory; output in `versions/.../build/`
    def atFile = rootProject.file 'src/main/resources/META-INF/accesstransformer.cfg'
    accessTransformers.from sc.process atFile, 'build/processed.cfg'
}
```

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

### Extract Loader from Project Name

Source: https://stonecutter.kikugie.dev/wiki/start/builds

Use sc.current.project to perform conditional logic based on the project directory name.

```kotlin
// Given projects are named `1.21.11-fabric`, `1.21.11-neoforge`, etc
val loader = sc.current.project.substringAfterLast('-')
```

```groovy
// Given projects are named `1.21.11-fabric`, `1.21.11-neoforge`, etc
def loader = sc.current.project.split('-')[1]
```

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

### Apply Swaps with Arguments

Source: https://stonecutter.kikugie.dev/wiki/config/params

Pass arguments to swap directives to populate template placeholders.

```java
void main() {
    //$ my_swap argument '"long quoted string"'
    method1(argument, "long quoted string");
}
```

```java
void main() {
    //$ my_swap argument '"long quoted string"'
    method2("long quoted string", argument);
}
```

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

### Configure Branch Version Synchronization

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Compare tree-level version aggregation versus independent branch definitions.

```kotlin
stonecutter.create(rootProject) {
    branch("A") { versions("1.0", "2.0") }
    branch("B") { versions("1.0", "3.0") }
}
```

```groovy
stonecutter.create getRootProject() {
    branch "A" { versions "1.0", "2.0" }
    branch "B" { versions "1.0", "3.0" }
}
```

```kotlin
stonecutter.create("A") { versions("1.0", "2.0") }
stonecutter.create("B") { versions("1.0", "3.0") }
```

```groovy
stonecutter.create "A" { versions "1.0", "2.0" }
stonecutter.create "B" { versions "1.0", "3.0" }
```

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

### Define Project Nodes

Source: https://stonecutter.kikugie.dev/wiki/start/settings

Registering supported versions within the root project tree.

```kotlin
stonecutter {
    // The root project is the Tree
    create(rootProject) { 
        versions("1.20.1", "1.21.1", "1.21.4")
    }
}
```

```groovy
stonecutter {
    // The root project is the Tree
    create(getRootProject()) { 
        versions "1.20.1", "1.21.1", "1.21.4"
    }
}
```

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

### Implement Branching Logic in Java

Source: https://stonecutter.kikugie.dev/wiki/start/comments

Chain conditions using elif and else to provide version-specific code paths.

```java
public static void example() {
    //? if 1.20.1 {
    System.out.println("Trails and Tales update just released!");
    //?} elif 1.21.1 {
    /*System.out.println("Tricky Trials update just released!");
    *///?} else if 1.21.4 {
    /*System.out.println("The Garden Awakens .. drop .. just dropped...");
    *///?}
}
```

```java
public static void example() {
    //? if 1.20.1 {
    /*System.out.println("Trails and Tales update just released!");
    *///?} elif 1.21.1 {
    System.out.println("Tricky Trials update just released!");
    //?} else if 1.21.4 {
    /*System.out.println("The Garden Awakens .. drop .. just dropped...");
    *///?}
}
```

```java
public static void example() {
    //? if 1.20.1 {
    /*System.out.println("Trails and Tales update just released!");
    *///?} elif 1.21.1 {
    /*System.out.println("Tricky Trials update just released!");
    *///?} else if 1.21.4 {
    System.out.println("The Garden Awakens .. drop .. just dropped...");
    //?}
}
```

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

### Define project versions

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Basic version definition for Stonecutter projects.

```kotlin
stonecutter.create(rootProject) {
    versions("1.20.1-fabric", "1.20.1-forge")
}
```

```groovy
stonecutter.create getRootProject() {
    versions "1.20.1-fabric", "1.20.1-forge"
}
```

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

### Dynamically map build scripts

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Use a closure to dynamically determine the build script path based on the project node.

```kotlin
stonecutter.create(rootProject) {
    mapBuilds { branch, node -> 
        "build-${node.project.substringAfter('-')}.gradle.kts"
    }

    versions(
        "1.20.1-fabric" to "1.20.1",
        "1.20.1-forge" to "1.20.1",
    )
}
```

```groovy
stonecutter.create getRootProject() {
    mapBuilds { branch, node -> 
        def loader = node.project.substring(node.project.lastIndexOf('-') + 1)
        "build-${loader}.gradle.kts"
    }

    versions [
        "1.20.1-fabric": "1.20.1",
        "1.20.1-forge": "1.20.1",
    ]
}
```

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

### Registering access converters in Gradle

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/accessconverters

Configuration for registering access converters in Kotlin and Groovy build scripts.

```kotlin
fletchingTable {
    accessConverter.register(sourceSets.main) {
        // Access widener file relative to `src/main/resources`
        // Converted to `META-INF/accesstransformer.cfg` by default
        add("example.accesswidener")
        
        // Optional destination parameter and extra converters
        add("extra.accesswidener", "META-INF/extra-accesstransformer.cfg")
    }
}
```

```groovy
fletchingTable {
    accessConverter.register("main") {
        // Access widener file relative to `src/main/resources`
        // Converted to `META-INF/accesstransformer.cfg` by default
        add("example.accesswidener")

        // Optional destination parameter and extra converters
        add("extra.accesswidener", "META-INF/extra-accesstransformer.cfg")
    }
}
```

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

### Select and expand access widener files in build scripts

Source: https://stonecutter.kikugie.dev/wiki/tips/resource-processing

Determine the correct access widener file based on the current Stonecutter version and expand the template in fabric.mod.json.

```kotlin
val minecraft = stonecutter.current.version
val accesswidener = when {
    stonecutter.eval(minecraft, ">=1.21") -> "1.21.accesswidener"
    stonecutter.eval(minecraft, ">=1.20") -> "1.20.accesswidener"
    else -> "1.19.accesswidener"
}

loom {
    accessWidenerPath = rootProject.file("src/main/resources/accesswideners/$accesswidener")
}

tasks.processResources {
    filesMatching("fabric.mod.json") {
        expand(mapOf(
            // other properties
            "aw_file" to accesswidener,
        ))
    }
}
```

```groovy
def minecraft = stonecutter.current.version
def accesswidener = stonecutter.eval(minecraft, ">=1.21") ? "1.21.accesswidener" 
    : stonecutter.eval(minecraft, ">=1.20") ? "1.20.accesswidener" 
    : "1.19.accesswidener"

loom {
    accessWidenerPath = rootProject.file("src/main/resources/accesswideners/${accesswidener}")
}

processResources {
    filesMatching("fabric.mod.json") {
        expand([
            // other properties
            aw_file: accesswidener,
        ])
    }
}
```

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

### Apply Fletching Table Plugins

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/setup

Apply the appropriate Fletching Table plugin based on the target environment.

```kotlin
plugins {
    id("dev.kikugie.fletching-table") version "0.1.0-alpha.22"
}
```

```kotlin
plugins {
    id("dev.kikugie.fletching-table.fabric") version "0.1.0-alpha.22"
}
```

```kotlin
plugins {
    id("dev.kikugie.fletching-table.neoforge") version "0.1.0-alpha.22"
}
```

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

### Configure access transformer template in neoforge.mods.toml

Source: https://stonecutter.kikugie.dev/wiki/tips/resource-processing

Define the access transformer file path using a template variable for dynamic resolution.

```toml
[[accessTransformers]]
file="accesstransformers/${at_file}"
```

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

### Configure String Replacements

Source: https://stonecutter.kikugie.dev/wiki/config/params

Define string replacements based on version conditions in build scripts.

```kotlin
stonecutter {
    replacements.string(current.parsed >= "1.21") {
        replace("io.github.me", "dev.me")
        // ...additional replacements
    }
}
```

```groovy
stonecutter {
    replacements.string(current.parsed.matches '>=1.21') {
        replace 'io.github.me', 'dev.me'
        // ...additional replacements
    }
}
```

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

### Define custom build scripts

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Assign specific build scripts to different project nodes.

```kotlin
stonecutter.create(rootProject) {
    versions("1.20.1-fabric" to "1.20.1")
        .buildscript("build-fabric.gradle.kts")
    versions("1.20.1-forge" to "1.20.1")
        .buildscript("build-forge.gradle.kts")
}
```

```groovy
stonecutter.create getRootProject {
    versions(["1.20.1-fabric": "1.20.1"])
        .buildscript "build-fabric.gradle.kts"
        versions(["1.20.1-forge": "1.20.1"])
            .buildscript "build-forge.gradle.kts"
}
```

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

### Standard flat language file

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

A traditional flat JSON language file structure.

```json
{
  "modid.item.foo": "Foo Item",
  "modid.item.bar": "Bar Item",
  "modid.block.foo": "Foo Block",
  "modid.block.bar": "Bar Block"
}
```

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

### Configure Stonecutter Plugin in settings.gradle

Source: https://stonecutter.kikugie.dev/wiki/start/settings

Initial plugin management and application configuration for Kotlin and Groovy DSLs.

```kotlin
pluginManagement {
    repositories {
        gradlePluginPortal()
        maven("https://maven.kikugie.dev/snapshots") { name = "KikuGie Snapshots" }
    }
}

plugins {
    id("dev.kikugie.stonecutter") version "0.9.7"
}

stonecutter {
    // Configuration goes here
}
```

```groovy
pluginManagement {
    repositories {
        gradlePluginPortal()
        maven {
            url = "https://maven.kikugie.dev/snapshots"
            name = "KikuGie Snapshots"
        }
    }
}

plugins {
    id("dev.kikugie.stonecutter").version "0.9.7"
}

stonecutter {
    // Enable Groovy DSL, as Stonecutter uses Kotlin by default
    kotlinController = false
    centralScript = "build.gradle"

    // Configuration goes here
}
```

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

### stonecutter.create

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Initializes a new tree within the Stonecutter configuration. Trees serve as synchronization points for subprojects.

```APIDOC
## stonecutter.create(name, configuration)

### Description
Creates a new tree for the specified project. The root project can be passed as the name, or a string identifier for separate trees.

### Parameters
- **name** (Project/String) - Required - The project instance or identifier for the tree.
- **configuration** (Closure/Action) - Required - The configuration block for the tree.
```

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

### Register custom entrypoint mappings

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/entrypoints

Add custom entrypoint interfaces to the annotation processor within the fabric extension block.

```kotlin
fletchingTable {
    fabric {
        entrypointMappings.put("modmenu", "com.terraformersmc.modmenu.api.ModMenuApi")
    }
}
```

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

### Set property via command line

Source: https://stonecutter.kikugie.dev/wiki/config/properties

Pass a property directly to a Gradle task execution.

```shell
./gradlew build -Pcom.example.property=true
```

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

### Assign Node Versions

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Use the versions function to create versioned project folders within a branch.

```kotlin
stonecutter.create(rootProject) {
    // Creates `versions/1.20.1/` and `versions/1.21.1/`
    versions("1.20.1", "1.21.1")
}
```

```groovy
stonecutter.create getRootProject() {
    // Creates `versions/1.20.1/` and `versions/1.21.1/`
    versions "1.20.1", "1.21.1"
}
```

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

### Define Stonecutter Trees

Source: https://stonecutter.kikugie.dev/wiki/config/settings

Register projects as trees within the settings build script.

```kotlin
// The root project is a tree
stonecutter.create(rootProject) {
}

// The `other` project is a separate tree
stonecutter.create("other") {
}
```

```groovy
// The root project is a tree
stonecutter.create getRootProject() {
}

// The `other` project is a separate tree
stonecutter.create "other" {
}
```

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

### Configure lifecycle tasks

Source: https://stonecutter.kikugie.dev/wiki/config/controller

Link external tasks to Stonecutter lifecycle or configure version switching behavior.

```kotlin
tasks.named("createMinecraftArtifacts") {
    dependsOn("stonecutterGenerate")
}
```

```kotlin
for ((project, switch) in stonecutter.tasks.switch) switch.configure {
    // doLast {}, dependsOn(), etc
}
```

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

### Parse Version Strings

Source: https://stonecutter.kikugie.dev/wiki/config/build

Convert a version string into a Stonecutter version object.

```kotlin
val version = sc.parse("0.110.3-beta.2")
```

```groovy
def version = sc.parse '0.110.3-beta.2'
```

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

### Compare Arbitrary Versions

Source: https://stonecutter.kikugie.dev/wiki/config/build

Compare two arbitrary version strings using the compare function.

```kotlin
if (sc.compare("1.21", "1.20") >= 0) {
    // ...
}
```

```groovy
if (sc.compare('1.21', '1.20') >= 0) {
    // ...
}
```

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

### Set active version via literal

Source: https://stonecutter.kikugie.dev/wiki/config/controller

Assign the active version using a literal string value.

```kotlin
stonecutter active "1.21.1"
```

```groovy
stonecutter.active '1.21.1'
```

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

### Define Local Swaps

Source: https://stonecutter.kikugie.dev/wiki/config/params

Define small, inline swaps directly within the source code.

```java
void example() {
    Clazz
        //$ if >=1.21 '.method1()' else '.method2()'
        .method1()
        .method3();
}
```

```java
void example() {
    Clazz
        //$ if >=1.21 '.method1()' else '.method2()'
        .method2()
        .method3();
}
```

```java
//$ if >=1.21 '.method1()' elif >=1.20 'method2()' else if >=1.20 'method3()' else '.method4()'
```

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

### Chain Version Predicates

Source: https://stonecutter.kikugie.dev/wiki/config/params

Demonstrates chaining multiple version predicates within a comment-based conditional block.

```java
public static void example() {
    //? if ~1.20 <1.20.4
    method();
}
```

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

### Register mixin configurations

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/mixins

Register mixin JSON files within the fletchingTable extension in build.gradle.kts, ensuring the files exist in the project.

```kotlin
fletchingTable {
    mixins.create("main") { // Name should match an existing source set
        // Default matches the default value in the annotation
        mixin("default", "example.mixins.json") 

        // Optionally add other mixin configs
        mixin("compat", "compat.mixins.json")
    }
}
```

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

### Nest Conditional Blocks

Source: https://stonecutter.kikugie.dev/wiki/config/params

Shows how to nest conditional blocks up to 10 levels deep using comment syntax.

```java
//? if <1.21 {
method1();
    //? if <1.20 {
    method2();
        //? if <1.19 {
        method3();
        //?}
    //?}
//?}
```

```java
//? if <1.21 {
/*method1();
    //? if <1.20 {
    /^method2();
        //? if <1.19 {
        /^¹method3();
        ¹^///?}
    ^///?}
*///?}
```

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

### Configure Gradle Build Properties

Source: https://stonecutter.kikugie.dev/wiki/start/builds

Sets the mod version, archive name, and dynamically selects the required Java version based on the Minecraft version. Includes standard dependency blocks for Minecraft and Fabric Loader.

```groovy
// These lines make the mod filename `{mod.id}-${mod.version}+${sc.current.version}.jar`
version = "${property('mod.version')}+${sc.current.version}"
base.archivesName = property('mod.id') as String

def requiredJava = 
    sc.current.parsed.matches('>=1.20.6') ? JavaVersion.VERSION_21 :
    sc.current.parsed.matches('>=1.18')   ? JavaVersion.VERSION_17 :
    sc.current.parsed.matches('>=1.17')   ? JavaVersion.VERSION_16 :
                                            JavaVersion.VERSION_1_8

dependencies {
    minecraft "com.mojang:minecraft:${sc.current.version}"
    mappings loom.officialMojangMappings()

    modImplementation "net.fabricmc:fabric-loader:${property('deps.fabric_loader')}"
}

java {
    withSourcesJar()
    sourceCompatibility = requiredJava
    targetCompatibility = requiredJava
}
```

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

### Check Version Equality

Source: https://stonecutter.kikugie.dev/wiki/config/build

Use the eq function to check for version equality, as direct operator overloading is not supported.

```kotlin
if (sc.current.parsed eq "1.21") {
    // ...
}
```

```groovy
if (sc.current.parsed.eq '1.21') {
    // ...
}
```

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

### Nested language file structure

Source: https://stonecutter.kikugie.dev/wiki/fletching-table/languages

A tree-like JSON structure to improve readability.

```json
{
  "modid": {
    "item": {
      "foo": "Foo Item",
      "bar": "Bar Item"
    },
    "block": {
      "foo": "Foo Block",
      "bar": "Bar Block"
    }
  }
}
```

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

### Apply String Swaps

Source: https://stonecutter.kikugie.dev/wiki/config/params

Use the swap directive in code to replace content based on the defined swap logic.

```java
public static void example1() {
    //$ my_swap
    method1();
}

public static void example2() {
    //$ my_swap
    method1();
}
```

```java
public static void example1() {
    //$ my_swap
    method2();
}

public static void example2() {
    //$ my_swap
    method2();
}
```
Tokens:
Raw