DOCSEARCHbyAlgolia
Submit Docs

Stonecraft Documentation

website·Indexed 32 days ago

https://stonecraft.meza.gg

A configuration Gradle plugin designed to eliminate boilerplate in Minecraft mod setup. It provides features for variable substitution in resources, access widening (since version 1.12.0), and wraps Stonecutter for multi-version workflows. The documentation covers modSettings configuration, clientOptions for options.txt, and migration guides for versions such as 1.7.x to 1.8.x.

Tokens
10.4K
Snippets
49
Records
87
Agent score
57%

What's inside Stonecraft

  1. Overview of Stonecraft Gradle plugin

    Stonecraft is a configuration Gradle plugin designed to eliminate boilerplate when setting up multi-loader and multi-version Minecraft modding workspaces. It provides a single codebase approach for Fabric, Forge, and NeoForge, reducing approximately 500 lines of repetitive build.gradle.kts code to a single line. It provides sensible defaults for modloader dependencies, data generation, the GameTest framework, and the Mod Publish plugin.

  2. Overview of Stonecraft multi-loader workspace

    Stonecraft allows developers to target Fabric, Forge, and NeoForge loaders within a single workspace. It achieves this by wiring these builds through Architectury and Stonecutter, eliminating the need to duplicate Gradle logic across different loader projects.

  3. Use the Stonecraft AI Agent Skill for development

    Stonecraft provides an AI agent skill designed to help AI coding agents better understand the Stonecraft framework and the basics of Stonecutter. This skill is specifically intended to prevent agents from misidentifying code comments as dead code and to ensure the agent follows the correct order of operations during development.

  4. Understand Stonecraft project structure and submodules

    Stonecraft, when used with Stonecutter, creates submodules for every minecraftVersion-loader pairing defined in the versions list. For example, having 4 Minecraft versions and 3 loaders results in 12 submodules.

    In Gradle configuration:

    • rootProject refers to the build.gradle.kts file in the project root.
    • project refers to the version-specific submodules located in the versions folder.

  5. Understand the impact of Mojang's deobfuscation on Minecraft Java Edition

    Starting with the first snapshot following the Mounts of Mayhem launch, Minecraft: Java Edition builds will include original class, field, method, parameter, and local names directly in the jars. This removes the need for obfuscation map entries in version JSONs and eliminates the need for Fabric Loader to perform remapping steps for these versions. This change results in logs, stack traces, and debugging sessions that match the names seen in the IDE.

  6. Install the Stonecraft skill for coding agents

    Install the Stonecraft agent skill to make the repository discoverable and usable by coding agents. The installation process writes the embedded skill to .agents/skills/stonecraft/SKILL.md and creates necessary parent directories. If the file already exists, the installer will not overwrite it to avoid losing project-specific edits unless the force flag is used.
    # Standard installation
./gradlew installStonecraftSkill

# Force overwrite existing skill file
./gradlew installStonecraftSkill --force-overwrite

  8. Migrate version declarations from vers() to version()

    Stonecutter 0.7 deprecated the vers() function used in settings.gradle[.kts] to declare project versions. Replace all instances of vers(...) with version(...).

    Warning: Ensure you use the singular version() function. The versions() function performs a different operation and is not a replacement for vers().

    // Change from:
fun mc(version: String, vararg loaders: String) {
    for (it in loaders) vers("$version-$it", version)
}

// To:
fun mc(version: String, vararg loaders: String) {
    for (it in loaders) version("$version-$it", version)
}

  9. Generate a new Stonecraft project

    The fastest way to start a new mod is using the Stonecraft project generator. The generator creates a complete workspace locally in the browser. Once generated, download the ZIP file, unzip it into a new directory, and follow the included README.

  10. Use variable substitution in Stonecraft resources

    Stonecraft hooks into the ProcessResources task to replace placeholders in resource files with values defined in the build.gradle[.kts] file. Variable substitution is automatically applied to all .json, .toml, and .mcmeta files in the resources directory.

    Exception: Language files within the assets folder are excluded from this process because Minecraft's own translation system is incompatible with Gradle's variable substitution.

    {
  "schemaVersion": 1,
  "id": "${id}",
  "version": "${version}",
  "name": "${name}",
  "description": "${description}",
  "entrypoints": {
    "main": [
      "${group}.${id}.ExampleMod"
    ]
  },
  "depends": {
    "fabricloader": "*",
    "fabric-api": ">=${fabricVersion}",
    "minecraft": ">=${minecraftVersion}"
  }
}

  11. Automate mod publishing to Modrinth and CurseForge

    Stonecraft supports automated publishing to Modrinth and CurseForge. A single Gradle invocation can be used to ship releases, handling shared changelogs, version metadata, and the generation of per-loader artifacts.

  12. Understand Stonecraft configuration order for overrides

    Stonecraft is designed to provide sensible defaults that can be overwritten by subsequent configurations in the build.gradle.kts file. To ensure your custom settings take effect, place them after the modSettings {} block. The recommended order of operations is: plugins, modSettings, repositories, dependencies, Architectury settings (fabricApi, loom), task overrides, and finally mod publishing.
    plugins {
    id("gg.meza.stonecraft")
}

modSettings {}

repositories {}
dependencies {}

// Architectury related settings
fabricApi {}
loom {}

// Task overrides
tasks.processResources {}

// Mod publishing
publishMods {}