How gnembon/fabric-carpet works
Project Type and Purpose
• This is a Minecraft mod built on Fabric. Its purpose is to extend and modify vanilla Minecraft for technical testing and control (e.g., testing farms, altering server TPS, logging, and providing extra in-game commands). The inclusion of “scarpet” (a scripting language for Carpet) also means there is a built-in extensible API and scripting feature.
• The README and file tree reveal that it is not a full-stack web application but a mod with a rich backend component including patches (mixins), scripting, commands, logging, network handling, and integration with Fabric’s mod loader.
Analyzing the File Structure
• Top-Level Files:
– Configuration and build files like build.gradle, settings.gradle, and gradle-wrapper files indicate that the build and dependency management is handled by Gradle.
• Key Directories and What They Represent:
– src/main/java/carpet: Contains the core mod classes (CarpetServer, CarpetExtension, CarpetSettings, etc.) which form the backbone of the mod’s functionality.
– src/main/java/carpet/commands: Houses implementation for various in-game commands (e.g., /tick warp, /log, /spawn).
– src/main/java/carpet/fakes and src/main/java/carpet/mixins: These packages include mixin classes that patch or extend vanilla Minecraft behavior. They represent cross-cutting modifications and integration points with Minecraft internals.
– src/main/java/carpet/script: This directory is dedicated to the “scarpet” scripting engine. It includes the parser, tokenizer, API definitions, language utilities, and exception handling. This forms the scripting subsystem that allows dynamic, in-game scripting.
– src/main/java/carpet/logging: Responsible for logging features, performance metrics, and possibly HUD related functionality.
– src/main/resources: Contains assets, language files, and additional resources that support mod localization and UI.
• Documentation and Examples:
– The docs folder (docs/scarpet) adds detailed documentation about the API and scripting language, showing that a well-defined developer and user guide exists.
a. Main Components:
– Fabric Mod Loader Integration: Represents the initialization point using the Fabric API. Key artifacts include fabric.mod.json and mod entry classes.
– Core Mod System: Comprises the core classes (CarpetServer, CarpetExtension, CarpetSettings) that initialize and configure the mod.
– Command System: All packages under carpet/commands that implement various mod-specific commands.
– Mixin/Patches Subsystem: The carpet/mixins (and patches) folder that shows systematic injection into vanilla Minecraft code. This part is essential in modifying Minecraft internals.
– Scarpet Scripting Engine: Encompassing the carpet/script package and related helpers in carpet/script/api and carpet/script/language. This subsystem is responsible for parsing, executing, and interfacing with custom script commands.
– Network Handlers: Under carpet/network, which manage communication between the client and server components.
– Logging and Diagnostics: Found in carpet/logging and carpet/utils directories. This subsystem monitors performance, events (TNT explosion logs, particle displays), and other in-game behaviors.
b. Relationships and Interactions:
– The Fabric mod loader triggers the mod’s initialization routine which instantiates the Core Mod System (CarpetServer, CarpetSettings).
– The Core creates command objects and sets up the scripting engine, which then interacts with the command system to provide in-game functionality.
– The Command System and Scripting Engine exchange data through defined APIs (e.g., carpet/script/api), and network handlers support client-server communications.
– Logging sub-components capture events from various modules, feeding back into diagnostics displayed (e.g., HUD or console).
– Gradle builds and configuration files are used during the build/deployment phase and are less on the runtime but essential for the project’s architecture.
c. Important Architectural Patterns:
– Use of Mixins: A dynamic code injection pattern for modifying behavior without altering the base code.
– Modular Components: Clear separation between commands, scripting, networking, logging, and core mod initialization.
– API and Scripting Separation: An extensible architecture that allows the scarpet scripting language to be independently maintained and extended.
– Dependency Injection-like patterns: Although not necessarily using a DI framework, key components like settings, command registration, and server extensions have clear interaction patterns.
d. Relevant Technologies, Frameworks, or Libraries:
– Gradle: For build and dependency management.
– Fabric Mod Loader: The underlying modding framework for Minecraft.
– Mixin Library: Utilized heavily for runtime modification of Minecraft classes.
– Java: The primary development language along with the platform’s JVM.
– JSON for resource localization (in src/main/resources/assets/carpet/lang).