> For the complete documentation index, see [llms.txt](https://mavenverse.gitbook.io/mavenverse-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mavenverse.gitbook.io/mavenverse-docs/freecarts/custom-models-guide.md). # Custom Models Guide FreeCarts supports custom 3D models for both minecarts and fuel stations using Minecraft Block Display entities, armor stand passenger mounts, and resource packs. ## 3D Cart Models (Blockbench & Resource Packs) ### How Cart Models Function FreeCarts renders 3D cart models in vanilla Minecraft without client-side mods: 1. When a model is applied, FreeCarts spawns an invisible, invulnerable, silent marker armor stand mounted as a passenger on the minecart. 2. The armor stand wears a `CARVED_PUMPKIN` item in its helmet slot configured with a specific `CustomModelData` integer. 3. Your server resource pack maps that `CustomModelData` integer to a custom 3D model JSON file. 4. When a player mounts the cart, FreeCarts mounts them directly onto the armor stand, synchronizing vehicle yaw, pitch, and position smoothly. *** ### Step 1: Model Creation & Blockbench Display Settings When modeling in Blockbench (Java Block/Item format): 1. **Geometry**: Keep models centered at `(0, 0, 0)` with the front of the cart facing North (`-Z`). 2. **Display Settings (Crucial)**: * Go to the **Display** tab in Blockbench. * Select the **Head** slot (this controls how the model appears when worn by the armor stand). * Set **Translation** to `[0, 13, 0]` (Y between 13 and 15 aligns the model flush with the ground/rails). * Set **Scale** to `[1, 1, 1]`. * Set **Rotation** to `[0, 0, 0]`. 3. **Export**: Export the model JSON (e.g. `sport_blue.json`) and texture PNG (`sport_blue.png`). *** ### Step 2: Resource Pack Configuration Place your model and texture files in your server resource pack: ``` assets/minecraft/ ├── models/ │ ├── item/ │ │ ├── carved_pumpkin.json # Overrides helmet item to display the 3D model │ │ └── minecart.json # Optional: displays 3D model when cart is in inventory/hand │ └── carts/ │ ├── sport_blue.json │ ├── sport_red.json │ └── sport_black.json └── textures/ └── item/ └── carts/ ├── sport_blue.png ├── sport_red.png └── sport_black.png ``` #### Override Configuration (`carved_pumpkin.json`) Map your `custom_model_data` IDs in `assets/minecraft/models/item/carved_pumpkin.json`: ```json { "parent": "minecraft:item/generated", "textures": { "layer0": "minecraft:item/carved_pumpkin" }, "overrides": [ { "predicate": { "custom_model_data": 11189820 }, "model": "item/carts/sport_blue" }, { "predicate": { "custom_model_data": 11189821 }, "model": "item/carts/sport_red" }, { "predicate": { "custom_model_data": 11189822 }, "model": "item/carts/sport_black" } ] } ``` > \[!NOTE] For Minecraft 1.21.4+ clients using the new `items/` component system, configure definitions under `assets/minecraft/items/carved_pumpkin.json` and `assets/minecraft/items/minecart.json`. *** ### Step 3: Server Registration in `models.yml` Register your models on the server in `plugins/FreeCarts/models/carts/models.yml`. #### Configuration Schema ```yaml models: : name: "" custom-model-data: ``` #### Naming Convention for Paint Color Variants To enable in-game color switching, name each model variant using the pattern: `_` The `` suffix must match an entry defined in `plugins/FreeCarts/models/carts/paint_colors.yml` (`blue`, `red`, `black`, `green`, `yellow`, `purple`, etc.). #### Complete `models.yml` Example ```yaml models: # Sport Cart Series sport_blue: name: "Sport Blue" custom-model-data: 11189820 sport_red: name: "Sport Red" custom-model-data: 11189821 sport_black: name: "Sport Black" custom-model-data: 11189822 # Offroad Buggy Series offroad_green: name: "Offroad Green" custom-model-data: 11189830 offroad_yellow: name: "Offroad Yellow" custom-model-data: 11189831 offroad_black: name: "Offroad Black" custom-model-data: 11189832 ``` *** ### Step 4: Configuring Paint Colors (`paint_colors.yml`) `plugins/FreeCarts/models/carts/paint_colors.yml` defines the available paint colors, GUI display materials, and economy purchase fees: ```yaml colors: blue: hex: "#1E90FF" display-name: "Blue" cost: 1000.0 material: "BLUE_CONCRETE" red: hex: "#DC143C" display-name: "Red" cost: 1000.0 material: "RED_CONCRETE" black: hex: "#282828" display-name: "Black" cost: 1000.0 material: "BLACK_CONCRETE" green: hex: "#228B22" display-name: "Green" cost: 1000.0 material: "GREEN_CONCRETE" ``` When a player holds a paintbrush tool (`/freecart customize paint`) or runs `/freecart variant`, FreeCarts matches the cart's `` with the selected color to switch to the corresponding model variant. *** ### Step 5: Applying and Testing in Game 1. Reload the plugin: ``` /freecart reload ``` 2. Verify all models are loaded: ``` /freecart model list ``` 3. Apply a model to a cart you are looking at: ``` /freecart model set sport_blue ``` 4. Give a player a cart pre-configured with a model: ``` /freecart give cart Steve --model sport_blue ``` 5. Remove a custom model: ``` /freecart model remove ``` *** ### Admin Troubleshooting | Issue | Cause | Solution | | ----------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Cart displays a literal Carved Pumpkin | `custom-model-data` mismatch or pack not loaded | Check that the integer in `models.yml` matches `carved_pumpkin.json` exactly. Ensure the player has downloaded and enabled the resource pack. | | Model has black/purple missing texture | Texture path error in model JSON | Verify that the `"textures"` paths inside your model JSON match the exact folder location of your PNG textures. | | Model floats above ground or sinks into rails | Incorrect Blockbench Head translation | In Blockbench, go to **Display** → **Head** and adjust Translation Y (13 to 15 is recommended). | | Model faces 90 degrees sideways | Incorrect export orientation | In Blockbench, orient the front of the cart toward North (`-Z`) before exporting. | | Model does not appear in `/freecart model list` | YAML formatting error or missed reload | Check console logs for YAML parsing errors and run `/freecart reload`. | *** ## Fuel Station Models (Block Display) Fuel station models utilize Minecraft 1.19.4+ Block Display entities generated through the [BDEngine](https://bdengine.app/) web editor. ### Creating and Exporting Models 1. **Design**: Build your fuel station model in BDEngine centered at `(0, 0, 0)` facing **South (+Z)**. FreeCarts automatically handles rotation matrices to align with the player's cardinal direction (`NORTH`, `SOUTH`, `EAST`, `WEST`) upon placement. 2. **Export**: Copy the generated `/summon block_display` command from BDEngine. 3. **Save Model Command**: Save the summon command line(s) into a text file in `plugins/FreeCarts/models/fuelstation/` (e.g. `gas_pump.txt`, `twin_pump.txt`, or in subfolders like `modern/neon_pump.txt`). ### Metadata & Hitbox Configuration (`.meta` File) Every fuel station model **MUST** have a matching `.meta` file in the same directory (e.g. `gas_pump.meta`, `twin_pump.meta`). #### Example `.meta` File ``` name: Example Twin Fuel Pump hitbox: 2,1,2 ``` *(Comment syntax `/* ... */` is also supported)* #### Metadata Syntax Breakdown * **`name:`** Display name shown in-game and in menus. * **`hitbox:`** Barrier block interaction hitbox dimensions formatted as a single comma-separated line: ``` hitbox: widthX,widthZ,height ``` * **`widthX`**: Base width across the X axis in blocks (e.g. `1` for a single pump, `2` for a double pump). * **`widthZ`**: Base depth along the Z axis in blocks (e.g. `1`). * **`height`**: Total height along the Y axis in blocks (e.g. `2`). > \[!IMPORTANT] A valid `.meta` file defining `hitbox: widthX,widthZ,height` is mandatory. If the `.meta` file or `hitbox:` definition is missing, FreeCarts will block placement in the world to protect against invalid barrier block generation. ### Importing and Managing Models * **Import Model**: `/freecart fuelstation model import ` (e.g. `/freecart fuelstation model import twin_pump` or `/freecart fuelstation model import modern/neon_pump`). * **List Available Models**: `/freecart fuelstation model list` * **View Model Details**: `/freecart fuelstation model info ` * **Get Placement Item**: `/freecart fuelstation give` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://mavenverse.gitbook.io/mavenverse-docs/freecarts/custom-models-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.