# ResourcePack AI — full documentation The complete text of the documentation at https://resourcepack.ai/docs, as one file. The machine-readable API description is at https://resourcepack.ai/docs/openapi.json. --- Source: https://resourcepack.ai/docs # ResourcePack AI ResourcePack AI makes Minecraft resource packs. A resource pack is the set of textures, models and sounds that changes how the game looks and sounds: a new look for stone, a sword with a custom model, a restyled inventory. You do it in **Studio**, a web app at [studio.resourcepack.ai](https://studio.resourcepack.ai). There's nothing to install. It works like this: 1. **Describe** what you want ("weathered copper roof tiles") and the AI makes a first version. Generating costs **AI Credits**, the app's currency; a free account gets 50 a month. 2. **Finish it** in the editors: a pixel editor for textures, a 3D editor for models, and editors for sounds, screens and the rest. 3. **Try it in Minecraft.** Join our free test server, press **Sync** in Studio, and the pack loads on your game in seconds. 4. **Export** it when it's done, as an ordinary pack file anyone can use. ## Where to start Quickstart Five minutes from sign-up to your first Block in game. Our test server Join and see what you made. ## What a pack can hold A **pack** is one project: everything for one server or one look. Each thing in it is an **asset** (one Block, one Model, one Sound), and each kind has its own tab. All of them can be generated or started blank, and most can be uploaded from files you already have. Models 3D objects built from cubes, edited in a Blockbench-style editor. Vehicles Models people can ride: seats, handling, sounds and effects. Mobs Models turned into creatures that walk, fight and drop loot. Blocks New textures for any vanilla block. Items Flat item sprites or 3D items, for the hand and the inventory. Armor Reskinned vanilla Armor sets, or 3D Armor. GUIs Restyled chests, furnaces, the inventory and other screens. Dialogs Screens a server opens over the game, with real buttons. HUD Hearts, hunger, the hotbar and the crosshair. Shaders Shapes, labels and bars over the screen, objects in the world, Text Effects and VFX. Icons Small pictures you can type into chat, signs and books, and Rank Tags. Sounds Sound effects that replace a vanilla one or add a new one. Emotes A wave, a dance, or a set of movements a player wears while walking. Models can also be [animated](/animations). [Skins](/skins) live on your account rather than in a pack. ## Testing it in Minecraft You don't have to export anything to see your work in game. Join our test server (, Java or Bedrock) and link your Minecraft account once with `/permlink`. From then on, the **Sync** button in Studio sends the pack to you while you stand there. Only you see it. The [Quickstart](/quickstart) walks through it. ## The plugins A resource pack can only change how things look. Some things need a plugin on the server too: placing a model that animates, driving a Vehicle, playing an Emote, opening a custom screen. - **[RP Engine](/testing/plugin)** is our main plugin, and the one Studio is built around. The test server already runs it, and you can install it on your own Paper, Spigot or Folia server, which also lets you sync to it. - **[Our other plugins](/plugins)** each do one job and don't need RP Engine: MC GUI for menus and shops written in HTML, Dialog Engine for Minecraft's own dialog menus, 3D Engine for real 3D models from `.glb` or `.obj` files. Java and Bedrock Bedrock players can join, link and receive packs too. Bedrock only accepts a pack while joining, so they're disconnected and reconnected for a few seconds each time. See [Bedrock and Geyser](/bedrock). ## When it's finished An [exported](/exporting) pack is an ordinary resource pack, with the same folders, JSON and PNGs the game expects. It works anywhere a pack works, including a server with nothing of ours installed. You can export a Java `.zip`, a Bedrock `.mcpack`, or content for other server plugins such as ItemsAdder, Nexo, Oraxen, CraftEngine and Model Engine. ## Where to go next Generating with AI What each type costs, and how to write a prompt that works. Packs Organising a pack, its versions and its settings. Exporting a pack Taking a finished pack anywhere a resource pack goes. Join the Discord Questions, bug reports, and what other people are building. ## Getting help - **Ask AI**, on every page of these docs, answers from the docs themselves. It can't see your account, your server or a link you paste, so paste the error text itself (the whole block, not one line) rather than a link to a log. - **Discord**: ask in the help channel at [resourcepack.ai/discord](https://resourcepack.ai/discord), or open a private ticket there for anything about your account, credits, billing or files you don't want to post in public. - **Email**: [support@resourcepack.ai](mailto:support@resourcepack.ai), if you'd rather not use Discord. For a plugin problem, include the plugin's version, your Minecraft version and server software (Paper, Spigot, Folia), and the console error. The whole of these docs is also one plain text file, [resourcepack.ai/docs/llms-full.txt](https://resourcepack.ai/docs/llms-full.txt), to read offline or to give to your own AI assistant. --- Source: https://resourcepack.ai/docs/3d-engine # 3D Engine 3D Engine puts real 3D models into vanilla Minecraft. Drop a `.glb`, `.gltf` or `.obj` file into a folder on your server, run `/3d reload`, and it is in the game: the actual mesh, with its own textures and animations, not a blocky remake. Furniture, statues, vehicles, props and creatures, anything you can download from Sketchfab or export from Blender. ![A real 3D car model standing on grass in Minecraft](/images/3d-engine.webp) The plugin bakes each file into a form the game can draw, builds a resource pack from them and sends it to players as they join. Players install nothing. ## What you need - **Spigot or Paper on Minecraft 26.3**, with **Java 21**. Players need to be on 26.3 too. - Nothing else. Models that walk use Paper's pathfinding on Paper and the engine's own on Spigot; everything else is the same on both. ## Installing Get the jar [Download 3DEngine.jar](https://cdn.resourcepack.ai/3DEngine.jar) (always the current release), or get it from [SpigotMC](https://www.spigotmc.org/resources/139510/). Drop it in and start the server Put it in `plugins/`. On first start it makes: ``` plugins/3DEngine/ config.yml models/ ← your 3D files effects/ ← shader effects, optional cache/ ← baked models, kept between restarts pack.zip ← the resource pack it built ``` The pack reaches players by itself The plugin uploads its pack to ResourcePack AI's free pack host (`packs.resourcepack.ai`) and players download it from there, so there is no port to open. It is only uploaded again when it changes, it is kept while your server uses it, and only the Minecraft client can download it. The host takes packs up to 95 MB. A bigger pack (lots of animated models) is served by your server instead, on port **8163**: open that port and set `pack.url` to the address players reach it on, such as `http://play.example.com:8163`. The console says when this happens. To always serve it yourself, set `pack.host: serve`. Add a model Put a model file in `plugins/3DEngine/models/` and run `/3d reload`. Then look at a block and run `/3d place `. ## The resource pack Every `/3d reload` builds a new pack, writes it to `plugins/3DEngine/pack.zip` and serves it. Players get it as they join, and everyone online is sent the new one when a reload changes it. **Already sending your own pack?** Set `pack.send: false` and merge `pack.zip` into yours after every reload. `/3d pack` sends you the engine's pack again, to check it arrives. **Adding your own files to it.** Anything in `plugins/3DEngine/pack/` goes into the pack at the same path, on the next reload: `assets/myserver/sounds.json` and its sounds, a font, an item model. Use a namespace of your own. A file at a path the engine writes itself (its shaders and models) is left out. The pack replaces some of the game's shaders Models are drawn by core shaders, so the pack replaces the game's `block`, `entity`, `item` and `terrain` shaders, and also `text` when you have any [shader effects](#shader-effects). Only one pack can replace a given shader. If another pack on the same client replaces one of these, whichever is higher in the list wins and the other's drawing breaks. That includes other plugins that use the `text` shader, such as RP Engine's shader objects. The models themselves live in a `3dengine` namespace and override nothing vanilla. ## Adding models - **Formats:** `.glb`, `.gltf` and `.obj`. Put an `.obj` file's `.mtl` and textures, or a `.gltf` file's `.bin` and textures, beside it. - **Names:** a model's name is its path under `models/`, lower case, without the extension: `models/furniture/armchair.glb` is `furniture/armchair`. - **Sketchfab downloads go in as they come.** Drop the `.zip` into the models folder and the next reload unpacks it into a folder of the same name. A `scene.gltf` (what every Sketchfab download contains) takes its folder's name, and its `.yml` is `scene.yml` beside it. Delete the unpacked folder to unpack the zip again. - **Baking is cached.** A reload only re-bakes models whose file, `.yml` or detail settings changed. It runs off the main thread, and `/3d reload` reports how many models and effects are ready, which failed and why, and how big the pack is. `/3d list` shows every model with its height and states. `/3d info ` adds its width, points, seats, hitboxes and what it costs the client. ## Placing models `/3d place [scale]` puts a model on the block you look at, facing you. `/3d give [player]` gives a model item: right-click a block to put the model there. The item shows the model as its icon and is not used up. Placed models are saved with the world. To change a placed model, look at it (within eight blocks) and use `/3d remove`, `/3d scale `, `/3d rotate `, `/3d state ` or `/3d sit [seat]`. **Sitting down.** Right-click a model with seats to sit in the nearest free one (everyone has `3dengine.ride` by default). Sneak to get off. Right-clicking while sneaking never sits you down. ## The model's .yml Any model file can have a `.yml` of the same name beside it: `armchair.glb` and `armchair.yml`. **Every key is optional.** Without one, a model comes in at its own size with one looping state per animation in the file (or a single still one). Positions in blocks (seats, hitboxes) are measured from the middle of the model's base: `x` to its right, `y` up, `z` forward. Any key 3D Engine doesn't use is kept for plugins to read, so an addon can keep its own settings beside a model. ### Size and placement ```yaml height: 1.8 # resize to this many blocks tall # scale: 0.5 # or: blocks per unit in the file (ignored when height is set) yaw: 90 # turn it so its front faces the way it is placed offset: [0, 0, 0] # move it, in blocks, after resizing hide: [Ground, Camera] # leave out parts of the file by node or bone name icon-scale: 1 # how big it is drawn as an item icon; fitted if left out ``` `hide` is for the extras a downloaded file often carries: a ground plane, a backdrop, a camera. Everything under a hidden node goes with it. ### States and animation A **state** is an animation the model loops: idle, walk, open. Without a `states:` block every clip in the file becomes one, named after the clip in lower case. ```yaml default-state: idle states: idle: {clip: Idle, fps: 10, syncs: 2} walk: {clip: Walk, fps: 20, wait: true} sit: {clip: Idle, pose: {Body: {rotate: [-40, 0, 0], translate: [0, -0.3, 0]}}} shuffle: {clip: Walk, blend: {clip: Idle, weight: 0.45}} transition-frames: 6 transitions: - idle <-> walk - {from: idle, to: sit, frames: 12} ``` | Key | Default | What it does | |---|---|---| | `clip` | | The animation in the file. A state with no clip is a still pose | | `fps` | `10` | Frames baked per second. More is smoother and makes a bigger pack | | `syncs` | `1` | How many evenly spaced points in the loop it can leave from | | `sync-at` | | Or the exact ticks it can leave from | | `wait` | `false` | Wait for a sync point before leaving, rather than cutting at the nearest | | `pose` | | Bones turned (degrees) or moved on top of the clip | | `blend` | | Mix in another clip: `clip`, `weight` (0 to 1) and `at` (seconds into it) | `default-state` is where a model starts: `idle` if there is one, otherwise the first state. A **transition** is a short blend from one state into another. `a -> b` is one way, `a <-> b` both ways, and the map form takes `frames` and `both-ways: true`. Each lasts `transition-frames` ticks (default 6) unless it says otherwise. Without one, a state change cuts straight across. **Animations from another file.** `animations-from: other.glb` drives this model with that file's clips, matched by bone name, and the other file is not loaded as a model. `retarget: {translate: [Body]}` limits which bones' movement carries over (all by default), and `rebind: [Bone]` moves the vertices of a bone nothing animates onto its neighbours. `legs:` lists IK chains, `{chain: [Upper, Lower], target: IKFoot}`, that keep feet planted. ### Points Named places that follow a bone through every animation, such as a mouth or a hand, for plugins to attach things to: ```yaml points: mouth: {bone: Head, at: [0, 2.1, 2.4]} ``` ### Looking at players ```yaml look: bone: Head # only the head turns; leave out to turn the whole model with: [Jaw] # more bones that turn with the head yaw: 70 # the most it turns either way, in degrees pitch: 35 range: 8 # blocks speed: 9 # degrees per tick states: [idle, sit] # the states it looks in; all if left out ``` `look: true` turns the whole model with these defaults, and `look: Head` does the same with a head bone. A turning head is drawn as a second model, so it costs one more item model per animation. Bones beside the head whose vertices sit inside it (a jaw, ears) turn with it anyway; `with:` adds any it misses. ### Seats and driving ```yaml seats: driver: {at: [-0.4, 0.5, 0.2]} passenger: {at: [0.4, 0.5, 0.2], bone: Body, pose: standing} drive: seat: driver # whose rider steers; the first seat if left out speed: 0.2 # blocks per tick sprint: 0.32 back: 0.08 turn: 7 # degrees per tick jump: 0.42 # 0 = it can't jump brain: horse # the invisible mob that carries it; picked by size if left out ``` A seat's `at` is where the rider's hips go, or their feet with `pose: standing`. With a `bone` the seat follows that bone through every animation. With `drive:`, whoever sits in the driving seat steers: the model goes where they look while they hold forward. `drive: true` uses the defaults above. The **brain** is an invisible mob under the model that does the moving, and its size decides which gaps the model fits through. If riders sit a little high or low, `seats.height-offset` in `config.yml` moves every seat at once. ### Hitboxes and solid models ```yaml hitboxes: - {at: [0, 0, 0.6], width: 1, height: 1.2} solid: true ``` Hitboxes make a model clickable. Unless you write your own they are fitted to the model: one box, or a row of up to six along a long model, so a car can be clicked at either end. `hitbox: {at, width, height}` is a single box of your own, and `hitbox: false` makes the model unclickable. `solid: true` fills a placed model's boxes with barrier blocks so nobody walks through it. Barriers only go in empty blocks, never where a rider sits, and are removed when the model is removed, moved or resized. A model that moves is never solid. ### Held as an item `item: true` lets the model be held. To set how it sits in each view, give a map of display contexts, as a block model's `display` does: ```yaml item: thirdperson_righthand: {rotation: [0, 90, 0], translation: [0, 2, 1], scale: 0.6} firstperson_righthand: {rotation: [0, 90, 0], scale: 0.5} ``` ### Walking `locomotion:` tells a model that walks which states to play and when: ```yaml locomotion: idle: idle walk: walk run: run turn: turn # turning on the spot walk-above: 0.035 # blocks per tick run-above: 0.13 ``` Each name defaults to the state of that name, if there is one. Plugins make models walk through the [API](#developer-api). ## Detail and pack size Each model is cut to a number of triangles, and its texture to a width, when it is baked. More is sharper, but makes the pack bigger and the game heavier for players. An animated model stores its whole mesh once per frame and its texture once per animation, so the texture is usually what makes a pack big. | Setting | Where | Wins over | |---|---|---| | `/3d quality [texture width]` | In game, saved to `quality.models` in `config.yml` | everything | | `triangles:` and `texture-width:` | The model's `.yml` | the server defaults | | `quality.triangles` and `quality.texture-width` | `config.yml` (20,000 and 512) | nothing | Nothing keeps more than `quality.max-triangles` (200,000) or `quality.max-texture-width` (2,048). `/3d quality` alone shows the defaults and every per-model setting; with a model it shows that model's. Setting one re-bakes it straight away. Because it lives in `config.yml`, a plugin that re-copies its own model files cannot undo it. `/3d quality reset` goes back to the model's own settings. ## Shader effects An **effect** is a small GLSL program drawn into the world: a fireball, a puff of flame, a black hole. Put `.glsl` files in `plugins/3DEngine/effects/` and run `/3d reload`. `/3d effect [size]` puts one where you look, `size` blocks across. `/3d effect` alone lists them, and `/3d effect clear` removes every one the command put down. Effects are not saved, so a restart clears them too. An effect file defines one function, from a ray to a colour: ```glsl vec4 object(vec3 ro, vec3 rd, float t0, float t1, float time, vec3 light, inout float depth) { // ... } ``` Each file is checked before it reaches anybody's graphics card and refused if it breaks a rule. The reload names any that were refused and why. - No `while` or `do` loops. Every `for` loop needs a literal bound of at most 160. - No preprocessor directives, uniforms, samplers, textures or `gl_` built-ins. - No `main()` and no `discard` (return an alpha of 0 instead). - At most 20,000 characters, and up to 255 effects. Effects replace the text shader The `text` shader is only replaced when the effects folder has an effect in it. Leave the folder empty if another plugin on your server needs that shader. ## Commands `/3d`, or `/engine3d`. `/3d` alone lists the subcommands you may use. From the console, a player's name at the end runs a command as that player: `/3d effect fire 2 Steve`. | Command | What it does | Permission | |---|---|---| | `/3d list` | Every model, its height and states, and any that failed to bake | `3dengine.list` | | `/3d place [scale]` | Places a model on the block you look at | `3dengine.place.command` | | `/3d give [player]` | A model item that places the model where it is used | `3dengine.give` (`.give.others` for another player) | | `/3d remove` | Removes the model you look at | `3dengine.remove` | | `/3d scale ` | Resizes it. `1` is normal size | `3dengine.scale` | | `/3d rotate ` | Turns it | `3dengine.rotate` | | `/3d state ` | Plays one of its states | `3dengine.state` | | `/3d sit [seat]` | Sits you in it, in a named seat or the nearest free one | `3dengine.sit` | | `/3d info [model]` | Size, states, points, seats, hitboxes and client cost | `3dengine.info` | | `/3d quality [model] [triangles\|reset] [texture width]` | Shows detail settings, or sets one model's and re-bakes it | `3dengine.quality` | | `/3d effect [size]` | Puts down a shader effect. `/3d effect clear` removes them | `3dengine.effect` | | `/3d reload` | Re-reads `config.yml`, re-bakes the models folder and re-sends the pack | `3dengine.reload` | | `/3d pack` | Sends you the pack again | `3dengine.pack` | ## Permissions All op-only by default except `3dengine.ride`. Somebody without a command's node is told which one they need. | Node | What it allows | |---|---| | The command nodes above | That command | | `3dengine.place` | Placing models with a model item from `/3d give`. A player without it can hold the item, but using it places nothing | | `3dengine.ride` | Sitting in a model's seats by right-clicking it. Everyone by default | | `3dengine.update` | Being told on joining that a newer 3D Engine is out | | `3dengine.admin` | Every command node and `3dengine.place`, but not `ride` or `update` | `3dengine.place.command` (any model, anywhere) is separate from `3dengine.place` (using an item you were given) so you can hand out model items without handing out `/3d place`. ``` /lp group builder permission set 3dengine.give true /lp group builder permission set 3dengine.place true /lp group admin permission set 3dengine.admin true ``` ## Configuration `plugins/3DEngine/config.yml`. `/3d reload` applies changes, except `pack.host`, `pack.port` and `pack.bind`, which need a restart (the reload tells you). If the file has a mistake, the reload says so and keeps the settings it had, and `/3d quality` refuses to save over it. | Key | Default | What it does | |---|---|---| | `pack.host` | `upload` | `upload` to ResourcePack AI's pack host, `serve` from this server over HTTP, or `none` | | `pack.port` | `8163` | The port it is served on (`serve`, or a pack too big to upload) | | `pack.bind` | empty | The address to listen on. Empty is all of them | | `pack.url` | empty | The address players download it from | | `pack.send` | `true` | Send it to players as they join | | `pack.required` | `false` | Kick players who decline it | | `pack.prompt` | empty | The message on the download prompt | | `pack.format` | `[97, 1]` | The pack format. Leave it alone | | `pack.description` | `3D Engine models` | The pack's description | | `quality.triangles` | `20000` | Default triangles per model | | `quality.texture-width` | `512` | Default texture width | | `quality.max-triangles` | `200000` | The most any model may keep | | `quality.max-texture-width` | `2048` | The widest any texture may be | | `quality.models` | `{}` | Per-model settings, written by `/3d quality` | | `seats.height-offset` | `0.0` | Raise (or, negative, lower) every seated rider, in blocks | | `update-check` | `true` | Ask SpigotMC as the server starts for a newer version, and tell the console and anyone with `3dengine.update` | | `telemetry` | `true` | An anonymous usage count sent to resourcepack.ai every 30 seconds: a random id, the number of players online and the names of plugins that depend on 3D Engine. No addresses, server names, player names or content | ## Developer API Add `depend: [3DEngine]` to your `plugin.yml`, compile against `3DEngine.jar` as a compile-only dependency, and call `Engine3D.get()`: ```java Engine3D engine = Engine3D.get(); engine.whenReady(() -> { ModelInstance chair = engine.place("furniture/armchair", location); // saved with the chunk chair.mount(player, null); // into the nearest free seat chair.lookAt(player); // or lookAround(), lookAway() ModelInstance dog = engine.spawn("dog", location); // not saved Mover legs = engine.mover(dog, EntityType.WOLF); legs.follow(player); }); ``` `whenReady` runs once every model is baked, and again after every `/3d reload`, so you can respawn what you drew against the new models. A plugin can copy its own model files into `engine.modelsFolder()` in `onEnable`: the first bake waits for the first tick. | Type | What it is | |---|---| | `Engine3D` | Models and instances: `spawn` (not saved), `place` (saved), `mover`, `item(model, state)` for an item that looks like the model, `effect`, `particle` and their variants, and `packFolder()` for files your plugin adds to the pack | | `Model` | A baked model: its states, points, seats, height, and the extra keys from its `.yml` | | `ModelInstance` | One model in the world: change state, find where a point is on any frame, scale, seat riders, look at things, turn hitboxes on and off | | `Mover` | Legs for a model: an invisible mob that follows, goes to a place, faces, and plays walk, run and turn to match its speed | | `EffectInstance`, `Particle` | Shader effects placed in the world, and ones the engine moves | `Engine3D.instance(entity)` finds the model any of its entities belongs to: its display, head, a hitbox, a seat or its brain. `Engine3D.near(location, radius)` lists the models around a place, nearest first, and `ModelInstance.mover()` is the mover walking a model about, if it has one (both since 0.1.6). ### Events All in `ai.resourcepack.engine3d.api.event`: | Event | When | Cancel to | |---|---|---| | `ModelInteractEvent` | A player right-clicks a model | Stop the default (sitting down) | | `ModelDamageEvent` | A player punches it, or a projectile or mob hits it | Tell later listeners | | `ModelMountEvent` | Something is about to sit in a seat | Keep them off | | `ModelDismountEvent` | A rider is getting off | Keep them on, when `isCancellable()` | | `ModelStateChangeEvent` | A new state's loop starts | | | `ModelSpawnEvent` / `ModelRemoveEvent` | A model is put down / taken away | | A model has no health of its own: what a hit does is up to you. [3D Pets](/3d-pets) is an addon built on nothing but this API. ## Credits The meshes are drawn by [obj³](https://github.com/JagerMeistars/obj-cubed), after Godlander's [objmc](https://github.com/Godlander/objmc). Its core shaders ship in the pack, with their licence. --- Source: https://resourcepack.ai/docs/3d-pets # 3D Pets An **addon** for [3D Engine](/3d-engine): a separate plugin that needs 3D Engine installed and uses it to draw, animate and walk its model. Drop it in beside the engine and it brings its own model with it. ![A 3D dog on the grass in Minecraft](/images/3d-pets.webp) This one is a dog, a real 3D Labrador rather than one made of blocks. Every player can call one. It trots after you, sits when you tell it to, potters about when you stand still, and plays fetch with a tennis ball. ## Installing Install 3D Engine first 3D Pets needs [3D Engine](/3d-engine) **0.1.1 or newer**, set up so that players get its resource pack. That is the one part worth checking: the dog is drawn by the engine's pack, and a player without it sees nothing. Drop it in [Download 3DPets.jar](https://cdn.resourcepack.ai/3DPets.jar), or get it from [SpigotMC](https://www.spigotmc.org/resources/139512/), and put it in `plugins/` beside `3DEngine.jar`. Then start the server. Call your dog The dog's and the ball's models install themselves into `plugins/3DEngine/models/3dpets/` and 3D Engine bakes them into its pack on startup. Type `/pet`. It runs where 3D Engine runs: **Spigot or Paper on Minecraft 26.3**, on **Java 21**. Players need nothing installed. ## What the dog does - **Follows you.** It walks to keep up, breaks into a run when you get far ahead, and if you leave it more than 24 blocks behind or change world, it catches up on its own. - **Sits.** Right-click it, or `/pet sit`, to sit it down, and again to get it up. Left alone it sometimes sits down by itself, and gets up when you move off. - **Potters about.** Stand still and it wanders near you, sniffs the ground, and now and then dashes off and back. - **Looks at you.** Standing or sitting about, it turns its head to whoever is near. - **Plays fetch.** See below. **One dog each.** It goes home when its owner leaves the server, and `/pet` again sends it home. Only its owner can sit it down: right-clicking somebody else's dog does nothing. ## Playing fetch `/pet ball` gives you a tennis ball. Throw it like a snowball and your dog runs after it, picks it up in its mouth, brings it back and drops it at your feet, where only you can pick it up. Throw it again. The ball is never lost. If the dog cannot reach it in time, or goes home while it has it, the ball goes back into your inventory. ## Commands | Command | What it does | |---|---| | `/pet` | Calls your dog, or sends it home if it is out | | `/pet sit` | Sits your dog down, or gets it up | | `/pet ball` | Gives you a tennis ball to throw | | `/pet throw [blocks]` | A testing tool: lands a ball that far ahead of you (15 if left out) and sends your dog for it | | `/pet debug` | A testing tool: traces every fetch, for every dog on the server, to the console and the owner's action bar. Run it again to turn it off | **From the console**, name the player first: `/pet Steve`, `/pet Steve throw 20`. If the dog is not ready yet, 3D Engine is still baking it, which takes a moment the first time the server starts with the plugin. ## Permissions | Node | Default | What it allows | |---|---|---| | `3dpets.use` | everyone | Having a dog: `/pet`, `/pet sit` and `/pet ball` | | `3dpets.debug` | op | `/pet debug`, turning fetch tracing on or off for every dog on the server | | `3dpets.throw` | op | `/pet throw`, landing a ball ahead of you for your dog to fetch | | `3dpets.admin` | op | Both testing tools, `3dpets.debug` and `3dpets.throw`, in one line | | `3dpets.update` | op | Being told on joining when a newer 3D Pets is on SpigotMC | `3dpets.use` is the node on the `/pet` command itself, so the two testing tools need it as well as their own node. Revoke it to turn the plugin off for a group without uninstalling anything. `3dpets.admin` is a convenience parent that nothing checks directly. Somebody without a tool's node is told which one they need, and tab completion leaves out the tools they cannot use. ## Configuration `plugins/3DPets/config.yml` has one switch: ```yaml # Tells you in the console, and anybody with 3dpets.update (ops) in chat, # when a newer 3D Pets is on SpigotMC. update-check: true ``` It asks SpigotMC once, as the server starts. Set it to `false` to turn it off. ## Changing the dog's detail The dog is an ordinary 3D Engine model called `3dpets/labrador`, and the ball is `3dpets/ball`. **3D Pets copies its own files back over them every time the server starts**, so editing the `.yml` in `plugins/3DEngine/models/3dpets/` does not last. To give the dog more or less detail, use 3D Engine's [quality setting](/3d-engine#detail-and-pack-size), which is kept in 3D Engine's own config and survives: ``` /3d quality 3dpets/labrador 6000 512 /3d quality 3dpets/labrador reset ``` ## Credits The Labrador is based on ["Labrador Dog"](https://sketchfab.com/3d-models/labrador-dog-1f56cfbab07e4fe49b5d9e521c82073a) by [kenchoo](https://sketchfab.com/kenchoo), itself based on ["Dog"](https://skfb.ly/oHLVz) by all of life, both licensed under [Creative Commons Attribution 4.0](http://creativecommons.org/licenses/by/4.0/), reduced, retextured and re-animated. Its animations are Quaternius' "Shiba Inu" (CC0). The credits are also copied beside the model, as `CREDITS.txt` in `plugins/3DEngine/models/3dpets/`. --- Source: https://resourcepack.ai/docs/affiliate # Affiliate programme Share your link, and when someone signs up through it, **40% of what they spend in their first year comes back to you as AI Credits**, the credits you spend on generating. There is no cash payout. There's nothing to apply for: every account has a link. Open **Affiliate** in the sidebar, press **Copy link**, and share it. ## What your link looks like Your link is the front page with your username on it: ``` https://resourcepack.ai/?ref=yourname ``` **Copy link** on the Affiliate page copies it. If you haven't set a username, one is made the first time you open the page; you can change it on **Account**, and the link changes with it. Someone counts as your referral if they **create an account within 60 days** of following your link. They don't have to sign up straight away or on the page they landed on. If they follow someone else's link before signing up, the most recent link wins. Who referred an account is settled when the account is created and never changes afterwards. An existing account can't be claimed later. ## Earning from the Gallery The [Gallery](https://resourcepack.ai/gallery) is where people share what they made. Anything you publish there carries your code. Anyone who signs up from one of your gallery pages is your referral, with no link to share. Items published **anonymously** earn nothing, because there's no creator to credit. The Affiliate page shows how many of your published items are earning and how many are anonymous. ## What you earn 40% of what a referred account pays, for 12 months from the day they signed up: | They buy | You earn | | --- | --- | | A subscription | 40% of every month they pay for, not only the first | | A credit top-up | 40% of it | | Supporter | 40% of it | | Nothing | Nothing | It's paid in AI Credits at the standard credit price ($0.05 a credit), rounded down to whole credits. So a $10 purchase earns you $4, which is 80 credits. They never expire and work like any other credits. The 12 months start when the account is created, not at their first purchase: someone who signs up today and subscribes in six months earns you six months of commission. ## When the credits land Each commission is **Pending** for 30 days, with its release date shown, and then becomes **Paid** and joins your balance. The wait covers the window in which a card payment can be refunded or charged back. If a payment is refunded while its commission is pending, the commission shows as **Refunded** and pays nothing. A commission that has already been paid stays yours. The **Earnings** list on the Affiliate page has one line per payment. ## Rules - **Referring yourself doesn't work.** A new account on the same device as the affiliate has its referral voided. - **You don't see who your referrals are.** The page shows how many there are and how many have paid, never names, usernames or emails. Sharing your link means agreeing to the [affiliate terms](https://resourcepack.ai/terms#affiliate): no self-referral, no spam, and nothing untrue about us. --- Source: https://resourcepack.ai/docs/animations # Animations You can make a model move: a door that swings open, a fan that spins, a chest lid that opens when someone walks up. You keyframe it in the model editor's **Animate** mode, or have the AI do it, and choose what makes it play. ![An animated Ferris wheel model, turning](/images/animations.webp) Vanilla Minecraft can't animate a model, so playback in game is done by [RP Engine](/testing/plugin), our server plugin. Our test server runs it. On Java, animations need RP Engine A pack with an animated model is still a valid resource pack, but the model stands still anywhere RP Engine isn't running. Bedrock is different: its pack carries the animations natively. See [On Bedrock](#on-bedrock). ## Animating in the editor Group what moves into bones Animate mode moves **cubes** and **bones** (named groups of cubes that share a pivot point, made in Edit mode). A hinge, a wheel or a wing should each be a bone, so it turns around one point. Generated models arrive already grouped, with pivots at the joints. Add keyframes Create an animation and give it a name and a length in seconds. Pick a cube or bone, move the playhead, and change its rotation, position or scale: a keyframe is set at that time. Keyframes past the end are dropped if you shorten the animation. Choose how it moves between keyframes Each keyframe has an interpolation: - **Linear**: a straight line between values. The default. - **Smooth**: a curve through the neighbouring keyframes. Good for anything organic. - **Step**: hold the value, then jump. Good for mechanical snaps. Before the first keyframe and after the last, the value holds still. Choose when it plays Pick one or more [triggers](#triggers): on a loop, when placed, when clicked, when a player comes near. An animation with no triggers never plays on its own, though a plugin can still play it by name. Try it in game On a server running RP Engine, press **Sync** (it sends the pack to you in game), then **Give in-game** on the model's page and right-click a block to place it. Sync again after each change. ### When it ends By default a one-off animation returns the model to its rest pose when it finishes. Tick **Stay on the last frame** and the model keeps that pose until another animation plays. Use it for a door that stays open, or for stages that build on each other. ### Animate with AI **Animate with AI** writes animations from a sentence, such as "gentle idle bob, tail sways behind". The result is ordinary keyframes you can edit. Use **Start from** to have the new animation carry on from the end of an existing one (**After** that animation) instead of from the base pose, which is how you build something in stages. It costs about 15 credits. Edits you make while it runs are kept: the result is merged onto your latest save. ### Importing from another model **Import animation** in Animate mode copies an animation from any other animated model in the pack. An animation that moves every part the same way (a tilt, a bob) goes onto every part of this model; anything else is matched by bone and cube names, or by order when both models have the same number of cubes. The dialog says how many parts it reached before you import. ## Triggers A model can have several animations, and each can have several triggers. | Trigger | Plays when | | --- | --- | | **On loop** | Continuously, while the model is placed | | **On placement** | Once, straight after the model is placed | | **On right click** | A player uses the model | | **On left click** | A player hits the model (this also makes it unbreakable) | | **On range** | A player comes within a radius of it (0.5 to 64 blocks) | How they behave: - **One animation per trigger.** If two animations both claim right-click, the first in the model's list plays. To choose a different one, use the **Plays** dropdown on the model's **Get in-game** card when you give it out. The choice rides on that item, so two copies of one model can play different animations. - **A playing animation isn't restarted.** Triggering it again while it's running does nothing. - **After a one-off finishes**, the model goes back to rest, or to its looping animation if it has one (unless it's set to stay on the last frame). - **Range fires on arrival.** It plays when someone walks into the radius, not every moment they stand in it, and can play again after they leave and come back. Left click makes a model unbreakable A model with an "On left click" trigger can't be punched to pick it up. Give players another way to remove it if they need one. ## Playing from a plugin A server plugin can play any animation by name, including one with no triggers, which is a good way to keep animations you drive from code from firing when someone clicks. With RP Engine installed: ```java RPEnginePlugin engine = (RPEnginePlugin) Bukkit.getPluginManager().getPlugin("RPEngine"); if (engine == null) return; // RP Engine isn't installed for (Placement statue : engine.models().near(altar, 8)) { statue.play("Wave"); } ``` You can find placed models near a location (`near`), in a chunk (`in`), or from a clicked entity (`at`), then `play`, `stop` or ask what's `playing()`. Call these on the main thread, and remember a model in an unloaded chunk isn't found. The full API, including listening for clicks on a model, is in [For plugin developers](/rp-engine/api). ## If it looks different in game - What you preview in the editor is what plays: the editor and RP Engine use the same keyframe maths. - RP Engine saves the animations it was sent, so placed models keep animating after a restart. If a model plays an old version, Sync again. - On Java the server updates moving parts ten times a second and the player's game smooths between updates, which keeps a build full of animated props cheap for the server. ## On Bedrock The Bedrock pack carries your keyframes as real Bedrock animations. On a server with Geyser, RP Engine still decides when an animation plays (same triggers, same rules), and the player's own client plays the frames, which looks smoother than Java. A Bedrock player only sees a placed model once the pack has been applied to them, because their client draws it from their own copy of the pack. ## Limits - Animations belong to one model. One model's trigger can't start another model's animation, though a plugin can play both. - Each placed copy remembers which way it was placed, so it animates the same way whichever direction you faced. - Someone who downloads your pack and plays without RP Engine sees every model in its rest pose. --- Source: https://resourcepack.ai/docs/api-reference # API overview The ResourcePack AI API is an HTTP API for doing from your own code what you do in Studio: create a pack, generate assets into it, and get the finished pack out. Use it for scripts, bots and tools of your own. To let an AI agent such as Claude do the work instead, use the [MCP server](/api-reference/mcp). What it covers: - **Packs**: create, rename, duplicate, delete, set the icon and style guide, invite collaborators, organise assets into folders. - **Generating**: Blocks, 3D Models, Items, GUIs, HUDs, Dialogs, Icons, Rank Tags, armour, Sounds, Shaders, VFX, Emotes, player Skins and Custom GUI pages. Then change any of them with a sentence (Edit with AI), regenerate them, or restore an earlier version. - **Your own files**: upload textures, models, sounds and more, or import a whole resource pack `.zip`. - **Getting it out**: export the Java `.zip`, a Bedrock `.mcpack` or plugin content, push the pack straight into a player's game, publish it to the servers bound to it, or put an asset on the public gallery. On every plan API keys are available on every plan, the free one included. Calls spend the same AI Credits the app does. There's no separate API pricing and no per-request charge. ## Base URL That host serves only the API. Every path in this reference is relative to it. The full spec is at [/openapi.json](/openapi.json). Every call needs a key, so start there. ## Get a key Open the Developers page Go to [studio.resourcepack.ai/developers](https://studio.resourcepack.ai/developers) and find the **API keys** card. The **MCP keys** card below it is for connecting an AI agent (see [MCP server](/api-reference/mcp)). Each kind of key only works on its own surface. Name it and create it The name is only for telling keys apart, so use what it's for: `ci`, `my bot`, `laptop`. Copy it immediately **The key is shown once.** We store only a hash of it, so we can't show it again. If you lose it, revoke it and make another. API keys are `rpai_` followed by 43 random characters (MCP keys start `rpai_mcp_`). The prefix makes a key that leaks into a commit or log easy to search for. Don't confuse these with **Bring Your Own Key** on your account page, which is a key you give us. These are keys we give your code. ## Authenticate Send the key as a bearer token: ```bash curl https://api.resourcepack.ai/v1/packs \ -H "Authorization: Bearer rpai_YOUR_KEY" ``` That's the only accepted way. Keys in query strings end up in logs and browser history, so they're refused. A key is your whole account It can read, generate into and export every pack you own or collaborate on, and it spends your credits. Keep it server-side: never in a Minecraft plugin, a browser bundle, or anything you hand to a player. Revoke it from the same card the moment you think it's out, and check its [history](/api-reference/history). ## Rate limits Each key gets **120 reads** and **30 writes** per rolling minute. A read is a `GET`; a write is any other request (creating a pack, generating, uploading, deleting), plus export. Over budget answers `429` with a `Retry-After` header. Credits still apply: a generation you can't afford is refused with `402`. See [Rate limits](/api-reference/rate-limits). ## What's not here The API doesn't do hand edits: painting pixels, moving a 3D Model's cubes, or laying out a Dialog piece by piece. Those happen in Studio's editors. It also doesn't make Mobs yet. If you need one of these from code, tell us in [Discord](https://resourcepack.ai/discord). Errors The error shape, and every code worth branching on. Jobs and polling Generation is asynchronous. How to wait properly. Create a pack The first call you'll make. Generating with AI What makes a prompt work. Applies here too. --- Source: https://resourcepack.ai/docs/api-reference/errors # Errors When a call fails, the HTTP status says roughly what kind of problem it is, and the body says exactly which. Every failure has the same shape: ```json { "error": { "code": "insufficient_credits", "message": "You don't have enough AI Credits for this." } } ``` Branch on `code`, never on `message`. The wording can change; the code won't. `message` is safe to show to a person. | Status | Code | What happened | | --- | --- | --- | | 400 | `invalid_request` | Something in the body or query is wrong; `message` says what | | 400 | `invalid_json` | The body wasn't a JSON object | | 400 | `invalid_job_handle` | A job handle that isn't `::` or `:import` | | 400 | `file_fetch_failed` | A file given by `url` couldn't be downloaded | | 400 | `not_a_pack` | An import's file isn't a resource pack, or holds nothing usable | | 400 | `no_file` | That asset has nothing in the `format` asked for: a 2D shader overlay and an emote have no picture, and only a VFX and a text effect have an animation | | 400 | `nothing_to_export` | The pack holds nothing that export format is built from yet, or it is all still generating | | 401 | `missing_api_key` | No `Authorization: Bearer` header | | 401 | `invalid_api_key` | The key isn't one of ours, or has been revoked | | 401 | `wrong_key_kind` | An MCP key sent to the REST API, or an API key sent to the MCP server | | 402 | `insufficient_credits` | Not enough AI Credits. Nothing was started or charged | | 402 | `distribution_cap` | This month's players are at your plan's limit, so a new release can't be published | | 403 | `plan_required` | The key is valid but the account's plan does not include the API | | 403 | `account_suspended` | The account is suspended; `message` says until when | | 403 | `forbidden` | Valid key, but not allowed to do this in this pack | | 403 | `pack_limit_reached` | Your plan's pack limit | | 403 | `asset_limit_reached` | This pack's asset limit | | 404 | `not_found` | No such pack, asset or job | | 404 | `job_not_found` | No job by that handle | | 404 | `upload_not_found` | No upload by that id. Uploads expire after 15 minutes and can be used once | | 404 | `no_such_player` | No account has verified that Minecraft username; invite them by email instead | | 409 | `conflict` | That vanilla target is already reskinned in this pack | | 409 | `already_running` | An AI edit or generation of that asset is still running | | 409 | `not_a_vehicle` | The model isn't a vehicle yet | | 409 | `not_linked` | Nobody is linked to receive a push; get a code from [`GET /packs/{pack}/link`](/api-reference/get-push-link) | | 409 | `skin_limit_reached` | The account holds as many skins as it may | | 409 | `server_limit_reached` | The pack is bound to as many servers as it may | | 409 | `still_generating` | You asked for an asset's file before it was ready | | 409 | `generation_failed` | That asset's generation failed; its job has the reason | | 413 | `file_too_large` | The file is over the limit for its use; `message` says the limit | | 429 | `rate_limited` | Over this key's budget; see [Rate limits](/api-reference/rate-limits) | | 429 | `too_many_invites` | The pack has as many invitations waiting as it may | | 429 | `daily_limit` | Publishing to the gallery: today's free title and description writing is used up. Send `title`, `description` and `tags` yourself, or try tomorrow | | 500 | `export_failed` | The export couldn't be built | | 500 | `request_failed` | Something went wrong with no more specific code | | 502 | `push_failed` | The pack was built but the player's server couldn't be reached, or refused it | | 503 | `unavailable` | The feature behind this endpoint is switched off | Each endpoint page lists the codes it can return, under **Error codes**. ## Credits and failures A generation reserves its credits when the job is **accepted**, not when it finishes. If the run fails, the credits are refunded automatically and the asset stays in the pack with the error on it. So a `402` means nothing started, and a job that ends in `error` has already been refunded by the time you read it. --- Source: https://resourcepack.ai/docs/api-reference/history # Key history Every key keeps a record of the work it did. On [studio.resourcepack.ai/developers](https://studio.resourcepack.ai/developers), press **History** on a key to see each action with its pack, asset and cost. The button appears once the key has done something. | Recorded | Not recorded | | --- | --- | | Generating, regenerating or editing anything | Polling a job | | Uploading, duplicating or deleting an asset | Listing packs, assets or the gallery | | Moving or copying assets to another pack | Downloading an asset file or a version | | Restoring an earlier version | Reading settings | | Creating, importing, exporting, changing, duplicating or deleting a pack | Filing assets in folders | | Changing the style guide, a model's or a sound's settings | Changing who you are told about | | Pushing to Minecraft, or giving an asset in game | Linking a player to receive pushes | | Publishing a release, or changing distribution | | | Inviting, changing or removing a collaborator | | | Publishing to the gallery, or copying from it | | Reads aren't recorded because a polling loop would bury the few lines that matter under hundreds of "still generating" checks. The cost shown is what was **actually charged**, not what was reserved up front. A generation that failed and was refunded, one covered by your own BYOK key, and a free action all show no cost. Revoking a key keeps its history. If a key leaks Revoke it from the Developers page. A revoked key stops working on the next request. Then read its history to see what it did while it was out. Keys can't create other keys, so a leaked key can't extend its own life. --- Source: https://resourcepack.ai/docs/api-reference/jobs # Jobs and polling Nothing generates inside a request. A block texture takes seconds and a model can take many minutes, so every generation endpoint answers **202 Accepted** straight away with a **job handle**, and you poll that handle. ``` POST /packs/my-pack/textures → 202 { "job": "my-pack:texture:mossy_bricks", … } GET /jobs/my-pack:texture:mossy_bricks → { "status": "generating", … } GET /jobs/my-pack:texture:mossy_bricks → { "status": "ready", "asset": { … } } GET /packs/my-pack/assets/texture/mossy_bricks → the PNG ``` | `status` | Meaning | | --- | --- | | `generating` | Still running. Keep polling. | | `ready` | Done. Fetch the file. | | `error` | Failed. `error` says why, and the credits have been refunded. | The job response also carries the full `asset`, so you don't need a second call to see what was made. ## Job handles A handle is `::`, which is also the asset's id: the asset itself is the job record. That means a handle keeps working long after the generation finished, and the [asset listing](/api-reference/list-assets) is how you recover handles from an earlier run. Treat the handle as an opaque string. To tell assets apart, read the asset's `type` field (`block`, `item3d`, `dialog` and so on), not the handle. A player [Skin](/api-reference/generate-skin) belongs to no pack, so its handle is `skin:` and its answer carries `skin` instead of `asset`. A [pack import](/api-reference/import-pack) has a different handle, `:import`. Polling it returns the same three statuses, plus an `import` report of what came in and what was left out. Shaders, VFX and emotes are kept apart from a pack's files, and an [AI edit](/api-reference/edit-asset) changes an asset that already exists, so their handles name that instead of a file format: `:shader:`, `:vfx:`, `:emote:`, `:emote_group:` and `:edit:`. They poll the same way and answer the same three statuses, without an `asset` in the answer. An edit's job reads `ready` once the change is saved. The [asset listing](/api-reference/list-assets) includes shaders, VFX, emotes and emote groups, with these handles as their ids. ## Polling always ends A loop that waits for the status to leave `generating` is safe to write. A run that dies without reporting reads as `error` after 25 minutes (45 for a 3D Model), so the loop always ends. How often to poll Every couple of seconds is plenty for blocks, items and icons, which come back in seconds. A model takes minutes, so back off: polling spends the key's read budget, and at two seconds a job, four jobs in flight is the most it covers. See [Rate limits](/api-reference/rate-limits). ## A full loop Create a pack, generate a block, wait, download the pack: ```bash #!/usr/bin/env bash set -euo pipefail API=https://api.resourcepack.ai/v1 AUTH="Authorization: Bearer $RPAI_KEY" pack=$(curl -s -X POST "$API/packs" -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"name":"Script Test"}' | jq -r .pack.slug) job=$(curl -s -X POST "$API/packs/$pack/textures" -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"prompt":"cracked obsidian with faint purple veins","mode":"vanilla","vanillaTarget":"stone","size":16}' \ | jq -r .job) while :; do status=$(curl -s "$API/jobs/$job" -H "$AUTH" | jq -r .status) [ "$status" != "generating" ] && break sleep 2 done if [ "$status" = "error" ]; then curl -s "$API/jobs/$job" -H "$AUTH" | jq -r .error >&2 exit 1 fi curl -s "$API/packs/$pack/export" -H "$AUTH" -o "$pack.zip" ``` A failed generation leaves the asset in the pack with its error, and the credits are already refunded, so always check the status you stopped on. --- Source: https://resourcepack.ai/docs/api-reference/mcp # MCP server Connect an AI agent (Claude, Cursor or any client that speaks the **Model Context Protocol**) and it can build a pack for you: create it, generate Blocks, 3D Models, Items, GUIs, Dialogs, Icons and Sounds, bring in files you already have, look at what came back, and try again where it's wrong. It is the same API as the rest of this reference, with the same AI Credits, and it needs a key of its own. The difference is that the agent gets a list of tools to call instead of URLs somebody has to program against. On every plan MCP keys are available on every plan, the free one included, and the MCP server spends the same AI Credits Studio does. There is no separate MCP pricing. ## Connect The server lives at **`https://api.resourcepack.ai/mcp`** and authenticates with an **MCP key** from the [Developers page](https://studio.resourcepack.ai/developers). MCP keys start `rpai_mcp_` and only work on the MCP server, and API keys only work on the REST API, so revoking the key you gave an agent never breaks your own code. The wrong kind of key is refused with `wrong_key_kind`. (Keys made before MCP keys existed work in both places.) Get an MCP key [studio.resourcepack.ai/developers](https://studio.resourcepack.ai/developers), the **MCP keys** card. Copy it straight away: it is only shown once. Add the server to your client In Claude Code: ```bash claude mcp add --transport http resourcepack-ai \ https://api.resourcepack.ai/mcp \ --header "Authorization: Bearer rpai_mcp_YOUR_KEY" ``` Any client that takes a JSON config wants this: ```json { "mcpServers": { "resourcepack-ai": { "type": "http", "url": "https://api.resourcepack.ai/mcp", "headers": { "Authorization": "Bearer rpai_mcp_YOUR_KEY" } } } } ``` Ask for something "Make me a pack of overgrown temple blocks: mossy bricks, cracked stone and a carved idol model." The agent will create the pack, generate into it, wait for the results and show you what it made. A key is your whole account It can read, generate into and export every pack you own or collaborate on, and it spends your credits. An agent you connect it to can do all of that without asking. Use a key created for the purpose so you can revoke it on its own, and keep an eye on [its history](/api-reference/history). ## What the agent gets One tool per endpoint in this reference, named after it, plus one that has no HTTP equivalent. Each name below links to the endpoint it calls, where the arguments are documented in full. | Tool | What it does | | --- | --- | | [`list_packs`](/api-reference/list-packs) | Every pack this key can reach, owned and shared. | | [`create_pack`](/api-reference/create-pack) | Start a new pack. | | [`get_pack`](/api-reference/get-pack) | One pack, and the oldest Minecraft version its contents load on. | | [`update_pack`](/api-reference/update-pack) | Rename a pack, change its description, or choose whose credits it spends. Owner only. | | [`set_pack_icon`](/api-reference/set-pack-icon) | The pack's icon, from a picture or one of its textures. Owner only. | | [`duplicate_pack`](/api-reference/duplicate-pack) | A new pack holding a copy of everything in this one. | | [`delete_pack`](/api-reference/delete-pack) | Delete a pack and everything in it. Cannot be undone. | | [`get_account`](/api-reference/get-account) | Your AI Credits and plan limits, so an agent knows what it can afford before generating. | | [`get_style_guide`](/api-reference/get-style-guide) | The pack's house style: palette, notes and reference pictures. | | [`set_style_guide`](/api-reference/set-style-guide) | Change the house style every visual generation follows. Owner only. | | [`list_assets`](/api-reference/list-assets) | What a pack holds, shaders, VFX and emotes included. Also how you recover a job handle from an earlier run. | | [`get_asset_file`](/api-reference/get-asset-file) | An asset's file. An image comes back as an image, and a VFX can come back as a picture of it playing. | | [`rename_asset`](/api-reference/rename-asset) | Change an asset's label. Its id stays, so nothing breaks. | | [`delete_asset`](/api-reference/delete-asset) | Delete an asset from a pack. Free, and it cannot be undone. | | [`duplicate_asset`](/api-reference/duplicate-asset) | A copy of an asset in the same pack. Free. | | [`transfer_assets`](/api-reference/transfer-assets) | Move or copy assets into another pack, or into a new one. Owner only. | | [`list_asset_versions`](/api-reference/list-asset-versions) | Every version an asset's AI edits and regenerates made. | | [`get_asset_version_file`](/api-reference/get-asset-version-file) | One earlier version, to compare. An image comes back as an image. | | [`restore_asset_version`](/api-reference/restore-asset-version) | Undo: put an asset back as it was. Later versions are discarded. | | [`list_asset_candidates`](/api-reference/list-asset-candidates) | The four versions a block, item or icon was drawn as, and which one the judge picked. | | [`get_asset_candidate_file`](/api-reference/get-asset-candidate-file) | One of those four, as an image. Creator, Studio and Teams. | | [`use_asset_candidate`](/api-reference/use-asset-candidate) | Switch the asset to another of the four. Free, Creator, Studio and Teams. | | [`list_folders`](/api-reference/list-folders) | The pack page's folders, and what is filed in each. | | [`create_folder`](/api-reference/create-folder) | Make a folder for one tab's assets. | | [`update_folder`](/api-reference/update-folder) | Rename or recolour a folder. | | [`delete_folder`](/api-reference/delete-folder) | Remove a folder. Its assets stay. | | [`file_assets`](/api-reference/file-assets) | Put assets in a folder, or take them out. | | [`list_collaborators`](/api-reference/list-collaborators) | Who else is in a pack, who is invited, and what each may do. Owner only. | | [`invite_collaborator`](/api-reference/invite-collaborator) | Invite somebody by Minecraft username or email. Owner only. | | [`update_collaborator`](/api-reference/update-collaborator) | Change what a collaborator may do. Owner only. | | [`remove_collaborator`](/api-reference/remove-collaborator) | Take somebody out of a pack. Owner only. | | [`revoke_invite`](/api-reference/revoke-invite) | Withdraw an invitation still waiting. Owner only. | | [`set_collaborator_notifications`](/api-reference/set-collaborator-notifications) | Choose what you are told about collaborators' work. Owner only. | | [`regenerate_asset`](/api-reference/regenerate-asset) | Run a generation again, or retry a failed one. Spends credits. | | [`export_pack`](/api-reference/export-pack) | Build the Java `.zip`, the Bedrock `.mcpack`, or the content for ItemsAdder, Nexo, Oraxen, CraftEngine or Model Engine. Confirms it built rather than returning it. | | [`push_pack`](/api-reference/push-pack) | Send the pack straight into Minecraft, like the Studio's Sync button. | | [`get_push_link`](/api-reference/get-push-link) | Who a push reaches, and the `/rp sync` code that links somebody. | | [`unlink_push`](/api-reference/unlink-push) | Stop pushes reaching the linked server. | | [`give_asset`](/api-reference/give-asset) | Give in game: the item in the player's hands, the screen opened, the sound played, the set worn. | | [`get_sound`](/api-reference/get-sound) | A sound's event, settings and takes. | | [`update_sound`](/api-reference/update-sound) | Change a sound's event, category, subtitle or loop, or choose which take ships. | | [`get_sound_take`](/api-reference/get-sound-take) | Hear one take before choosing it. Comes back as audio. | | [`copy_sound_take`](/api-reference/copy-sound-take) | Make a new sound from one take. | | [`delete_sound_take`](/api-reference/delete-sound-take) | Throw one take away. | | [`publish_pack`](/api-reference/publish-pack) | Publish a release every bound server hands its players. | | [`publish_to_gallery`](/api-reference/publish-to-gallery) | Put an asset on the public gallery, with its title and description written for you if you leave them out. | | [`list_gallery`](/api-reference/list-gallery) | Browse and search what people have published to the public gallery. | | [`get_gallery_item`](/api-reference/get-gallery-item) | One gallery item. | | [`copy_from_gallery`](/api-reference/copy-from-gallery) | Copy a gallery item into one of your packs. Free. | | [`get_distribution`](/api-reference/get-distribution) | What bound servers serve, how a release's build is going, and which versions it can be built for. | | [`update_distribution`](/api-reference/update-distribution) | Turn serving on or off, and choose the versions the next release is built for. | | [`get_distribution_stats`](/api-reference/get-distribution-stats) | Players served, what their clients did with the pack, their versions, and serves per day. | | [`list_distribution_servers`](/api-reference/list-distribution-servers) | The servers bound to a pack, and any claim code still waiting. | | [`bind_distribution_server`](/api-reference/bind-distribution-server) | A `/rp distribute` code for somebody to type on their server. | | [`rename_distribution_server`](/api-reference/rename-distribution-server) | Change the name a bound server is shown by. | | [`unbind_distribution_server`](/api-reference/unbind-distribution-server) | Stop a server handing out the pack. Cannot be undone. | | [`list_distribution_serves`](/api-reference/list-distribution-serves) | The most recent times a server handed the pack to a player. | | [`list_distribution_players`](/api-reference/list-distribution-players) | Every player a bound server has handed the pack to. | | [`create_upload`](/api-reference/create-upload) | A URL to put a file into, for anything too big to send inline. | | [`upload_asset`](/api-reference/upload-asset) | Put a file you already have into a pack: a texture, sprite, icon, model, sound, GUI, HUD or armour. Free. | | [`upload_reference`](/api-reference/upload-reference) | A reference picture for a generation to follow. | | [`import_pack`](/api-reference/import-pack) | A whole resource pack `.zip` as a new pack, like the Studio's Import button. Free. | | [`generate_texture`](/api-reference/generate-texture) | A block texture. | | [`generate_model`](/api-reference/generate-model) | A 3D model. The slow one: minutes, not seconds. | | [`generate_mob`](/api-reference/generate-mob) | A mob: a creature built, animated and given its own sounds in one run. The slowest: ten to twenty minutes. | | [`generate_item`](/api-reference/generate-item) | An item, as a flat sprite or real geometry. | | [`generate_gui`](/api-reference/generate-gui) | A container screen: chests, furnaces and the rest. | | [`generate_hud`](/api-reference/generate-hud) | The overlay drawn over the world: hearts, hunger, hotbar, crosshair. | | [`generate_dialog`](/api-reference/generate-dialog) | A dialog: a server menu in Minecraft's own look, opened with `/dialog`. | | [`generate_icon`](/api-reference/generate-icon) | A bitmap glyph you can type into chat, signs and books. | | [`generate_rank_tag`](/api-reference/generate-rank-tag) | A rank tag for a LuckPerms prefix or suffix, like a red OWNER badge. Done when it answers. | | [`generate_armor`](/api-reference/generate-armor) | An armour set: a reskin of a vanilla set, or 3D armour worn on the player. | | [`generate_sound`](/api-reference/generate-sound) | A sound effect. | | [`generate_shader`](/api-reference/generate-shader) | A shader: a HUD overlay (done when it answers), a 3D object in the world, or a text effect. | | [`generate_vfx`](/api-reference/generate-vfx) | A VFX: an effect of glowing sprites played in the world. | | [`generate_emote`](/api-reference/generate-emote) | A player animation, played in game with `/emote`. Minutes, not seconds. | | [`create_emote_group`](/api-reference/create-emote-group) | A movement group: a walk, run, crouch and jump of your own, worn as one. Free. | | [`update_emote_group`](/api-reference/update-emote-group) | Rename a movement group, or change which emote plays in each state. | | [`get_model`](/api-reference/get-model) | A model's settings: its type, whether it stops vehicles, its animations. | | [`update_model`](/api-reference/update-model) | Whether a placed copy stops vehicles; convert it to a vehicle or a mob and back. | | [`export_model`](/api-reference/export-model) | One model as a resource pack of its own, for one Minecraft version. | | [`get_armor3d_file`](/api-reference/get-armor3d-file) | A 3D armour set as a Blockbench project, or its texture. | | [`get_item_states`](/api-reference/get-item-states) | The states an item is drawn in, like a bow drawn back, and their looks. | | [`set_item_state`](/api-reference/set-item-state) | Give an item a look of its own for one state. | | [`list_custom_guis`](/api-reference/list-custom-guis) | A pack's Custom GUIs (MC GUI pages), and the templates to start one from. | | [`create_custom_gui`](/api-reference/create-custom-gui) | Make a Custom GUI, blank or from a template. | | [`get_custom_gui`](/api-reference/get-custom-gui) | A Custom GUI's HTML and CSS files. | | [`update_custom_gui`](/api-reference/update-custom-gui) | Write or remove a Custom GUI's files, or rename it. | | [`delete_custom_gui`](/api-reference/delete-custom-gui) | Delete a Custom GUI. | | [`share_custom_gui`](/api-reference/share-custom-gui) | A code for `/mcgui import` on a server running MC GUI. | | [`generate_custom_gui_page`](/api-reference/generate-custom-gui-page) | Have the AI write or rewrite one of a Custom GUI's pages. Done when it answers. | | [`list_tooltips`](/api-reference/list-tooltips) | A pack's Tooltips: the boxes items show when hovered. | | [`generate_tooltip`](/api-reference/generate-tooltip) | Design a Tooltip from words. Done when it answers. | | [`get_tooltip`](/api-reference/get-tooltip) | A Tooltip's design, give command and item components. | | [`get_tooltip_picture`](/api-reference/get-tooltip-picture) | A Tooltip drawn as the game draws it, as an image. | | [`update_tooltip`](/api-reference/update-tooltip) | Change a Tooltip's design by hand, or rename it. | | [`edit_tooltip`](/api-reference/edit-tooltip) | Change a Tooltip with AI. Done when it answers. | | [`delete_tooltip`](/api-reference/delete-tooltip) | Delete a Tooltip. | | [`list_loading_screens`](/api-reference/list-loading-screens) | A pack's Loading Screens: the screen Minecraft shows while packs load, restyled. | | [`generate_loading_screen`](/api-reference/generate-loading-screen) | Design a Loading Screen from words. Done when it answers. | | [`create_loading_screen`](/api-reference/create-loading-screen) | Add a Loading Screen from a ready-made look or your own spec. Free. | | [`get_loading_screen`](/api-reference/get-loading-screen) | A Loading Screen's design. | | [`update_loading_screen`](/api-reference/update-loading-screen) | Change a Loading Screen by hand (a picture logo too), or make it the one the pack shows. | | [`edit_loading_screen`](/api-reference/edit-loading-screen) | Change a Loading Screen with AI. Done when it answers. | | [`delete_loading_screen`](/api-reference/delete-loading-screen) | Delete a Loading Screen. | | [`get_vehicle`](/api-reference/get-vehicle) | A vehicle's settings: seats, handling, hitbox, animations, sounds. | | [`set_vehicle`](/api-reference/set-vehicle) | Make a model a vehicle, or change its settings. Free. | | [`rig_vehicle`](/api-reference/rig-vehicle) | Animate a vehicle and its riders together. Minutes, not seconds. | | [`rig_mob`](/api-reference/rig-mob) | Animate a mob: one animation per state (walk, attack, hurt, death...). | | [`edit_asset`](/api-reference/edit-asset) | Change something that already exists from a sentence, like the Studio's Edit with AI. Also animates a model. | | [`list_skins`](/api-reference/list-skins) | Your player skins. | | [`generate_skin`](/api-reference/generate-skin) | A 64x64 player skin from a description. | | [`get_skin`](/api-reference/get-skin) | One skin, and whether it's finished. | | [`get_skin_file`](/api-reference/get-skin-file) | A skin's PNG. Comes back as an image. | | [`push_skin`](/api-reference/push-skin) | Wear a skin in game now, like the skin editor's Sync. | | [`delete_skin`](/api-reference/delete-skin) | Delete a skin. | | [`get_job`](/api-reference/get-job) | One generation's status. Usually `wait_for_job` is what you want instead. | | `wait_for_job` | **No HTTP equivalent.** Waits for generations to finish, so the agent doesn't poll. | The tools are generated from the same source as this reference and the [OpenAPI document](/openapi.json), so they take the same arguments, limits and enums. An endpoint that is switched off is left out of the list. ### `wait_for_job` waits, so the agent doesn't poll Every generation is [asynchronous](/api-reference/jobs): you get a job handle and poll it. For an agent, each poll costs a whole turn, so `wait_for_job` does the waiting on the server instead. The agent passes every handle it is waiting on in one call and gets one answer when they have all finished. It waits up to 50 seconds, because most MCP clients give up on a request after a minute. If time runs out it says which jobs are still going and the agent calls again, as often as it takes. Nothing is lost or charged twice. ### Files come back as files `get_asset_file` returns a generated texture, sprite or icon **as an image**, so the agent can actually look at what it made before telling you it is done, and regenerate it if it is wrong. Sounds come back as audio, models as their JSON. ### Changing what's there, and what it costs There are three ways to change an asset, and only one is free: | Change | Tools | AI Credits | | --- | --- | --- | | By hand, from a file | `upload_asset` (a file you made), `update_custom_gui` (a Custom GUI's HTML and CSS), `update_tooltip` (a Tooltip's design), `update_loading_screen` and `create_loading_screen` (a Loading Screen's design), the settings tools (`update_sound`, `set_vehicle`, `update_model`, `set_item_state`...) | Free | | Housekeeping | `rename_asset`, `duplicate_asset`, `delete_asset`, `file_assets`, `restore_asset_version` (undo an AI change), `use_asset_candidate` (another of the four versions, Creator, Studio and Teams) | Free | | With AI | `edit_asset`, `regenerate_asset`, `rig_vehicle`, `rig_mob`, `generate_custom_gui_page`, `edit_tooltip`, `edit_loading_screen`, every `generate_*` | Spends credits, at Studio's prices | **Dialogs have no hand-edit tool.** A Dialog can't be uploaded or written as JSON, so an agent changes one only through `edit_asset`, addressed as `texture/gui:`. This works on Dialogs in Minecraft's own look (Dialog style): - `mode: "edit"` changes one page from a sentence ("add a Close button", "reword the title"). - `page` picks the page (the first by default). Each call is one page and costs a flat 15 AI Credits, finished when it answers. `regenerate_asset` makes a whole new Dialog at the price of generating one. `restore_asset_version` puts back an earlier version for free. To move pieces, change a button's command or fix a word without spending credits, open the Dialog in Studio's editor. ### Sending files in `upload_asset`, `upload_reference` and `import_pack` take a `file` in one of four forms: - **`text`**: the file as text, such as a model's JSON the agent wrote itself. - **`base64`**: the bytes inline. Fine for a 16px texture. - **`url`**: a public `https` address to fetch it from. - **`upload`**: the id from `create_upload`, after the bytes were PUT to the URL it returned. Use `upload` for any file on disk. An agent with a shell sends the bytes itself, so they never pass through the model: ```bash curl -T lantern.bbmodel "" ``` Base64 works too, but an agent writes it a token at a time, so it is slow and expensive for anything bigger than a small image. An import runs after `import_pack` answers, like a generation: the agent waits on its job (`:import`) with `wait_for_job`, and `get_job` then has the full report of what came in and what was left out. `export_pack` confirms the export built and how big it is, but doesn't return the file, which is megabytes an agent has no use for. Download it over HTTP with an **API** key (an MCP key is refused there): ```bash curl -H "Authorization: Bearer $RPAI_KEY" -o pack.zip \ https://api.resourcepack.ai/v1/packs/YOUR_PACK/export ``` ## Limits and behaviour | | | | --- | --- | | **Transport** | Streamable HTTP. POST JSON-RPC. The server doesn't open a message stream, so a `GET` answers 405. | | **Sessions** | None. Every request carries the key and stands alone, so a dropped connection costs nothing. | | **Rate limits** | The same budgets as the REST API: [120 reads and 30 writes a minute](/api-reference/rate-limits) per key. `wait_for_job` paces its own polling to stay inside the read budget. | | **Errors** | A failed call comes back as a tool error the agent can read and act on, carrying the same [stable code](/api-reference/errors) the REST API uses. | | **Origin check** | The two [origin-check endpoints](/api-reference/origin) are not tools. They need no key and exist for marketplaces, who are better served over HTTP. | Tell it what you want, not how The server gives the agent its own briefing (what a pack is, that generating costs credits, how to tell assets apart by `type`), so you don't have to explain any of it. Describe the pack you want and let it choose the calls. Jobs and polling What `wait_for_job` is doing on your behalf. Rate limits The budgets an agent is spending. Key history What the agent did, and what it cost. Generating with AI What makes a prompt land. Applies here too. --- Source: https://resourcepack.ai/docs/api-reference/origin # Origin check **Two unauthenticated endpoints that answer one question: did this file come out of ResourcePack AI?** They exist for marketplaces. If you require AI-generated work to be labelled, or don't accept it at all, you can't reliably tell by looking. We don't support reselling generated packs, and these endpoints let you check for yourself. No key or account is needed. ## What an answer means The two verdicts are not symmetrical. Don't treat them as if they were. **`generated` is definitive.** The content in front of you was produced here. There is no heuristic and no confidence score: the hash is either in the registry or it isn't. **`no_record` means only "not in our registry".** It is not evidence that a human made the file. It could be somebody's own work, another generator's output, or ours after an edit. ## Why there are no false positives A `generated` verdict is safe to act on because of three rules. **Only our own output is registered.** A pack holds work we generated and work its owner brought in, and the two are tracked separately. Imported artwork is never fingerprinted, so a creator who edits their own texture in Studio can't have it called ours. **Generic content is left out.** A blank tile, a square of one colour or a model with no geometry of its own is something thousands of people have made independently. Anything below a minimum of distinctness is skipped, so the registry can't hold a hash that belongs to somebody else's work. **Content is registered on the way out.** It is fingerprinted when it leaves Studio (exported, pushed, published or downloaded), not when it is generated, so the registry records what could actually have reached you. Where there is doubt, nothing is registered and the answer is `no_record`. ## Computing the hash **SHA-256 over the file's canonical content, not its bytes.** Re-saving a PNG, stripping metadata, reordering JSON keys or pretty-printing all leave the answer unchanged. Only editing the actual content changes it. Three forms, chosen by file extension. ### `.png` Decode to 8-bit RGBA. Set every **fully transparent** pixel to `00 00 00 00` first (encoders disagree about what goes in the colour channels under alpha 0). Then hash: ``` "rpai/v1/png\n" + "x\n" + ``` The dimensions are part of the input, so a 16×32 and a 32×16 texture with the same pixels hash differently. ### `.json` Parse it, then serialise canonically: object keys sorted, **array order kept** (in a block model, element order is the geometry), numbers rounded to six decimal places with `-0` written as `0`, and no whitespace anywhere. Then hash: ``` "rpai/v1/json\n" + ``` The rounding absorbs float noise: some editors write `0.3` back out as `0.30000000000000004`. ### Everything else Sounds and any other file are hashed as stored: ``` "rpai/v1/bytes\n" + ``` So a re-encoded `.ogg` is a different hash and reads as `no_record`. The prefixes are hashed, not labels `rpai/v1/png` and the others are part of the input to SHA-256, newline included. Getting one wrong means every lookup silently misses. The format is frozen: a change would appear as `rpai/v2/…`, never as an edit to these. ## Try it without writing anything Both endpoint pages have a **Try it** button that takes a file: drop in a pack `.zip`, a `.mcpack`, or loose `.png` / `.json` / `.ogg` files, and it hashes them and fills in the request. **The hashing happens in your browser.** The pack never leaves your machine; only the 64-character hashes are sent. That hasher is tested against ours on the same files, so its digests are what the registry stores. Hash something you generated with us and confirm it comes back `generated` before writing any code. ## Reference implementations The same rules in three languages. Each turns a file into the 64 hexadecimal characters the endpoints take. Check yours against **Try it** on a file you generated with us before you trust it. ```js // Needs a PNG decoder; everything else is the standard library. import { createHash } from "node:crypto"; import { PNG } from "pngjs"; function canonicalJson(value) { if (value === null || value === undefined) return "null"; if (typeof value === "number") { if (!Number.isFinite(value)) return "null"; const r = Math.round(value * 1e6) / 1e6; return Object.is(r, -0) ? "0" : String(r); } if (typeof value === "boolean") return value ? "true" : "false"; if (typeof value === "string") return JSON.stringify(value); if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; const entries = Object.entries(value) .filter(([, v]) => v !== undefined) .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)); return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`; } export function fingerprint(fileName, bytes) { const name = fileName.toLowerCase(); const sha = createHash("sha256"); if (name.endsWith(".png")) { const png = PNG.sync.read(bytes); // png.data is RGBA8, row-major const pixels = Buffer.from(png.data); for (let i = 0; i < pixels.length; i += 4) { if (pixels[i + 3] === 0) pixels.fill(0, i, i + 4); } sha.update("rpai/v1/png\n"); sha.update(`${png.width}x${png.height}\n`); sha.update(pixels); } else if (name.endsWith(".json")) { sha.update("rpai/v1/json\n"); sha.update(canonicalJson(JSON.parse(bytes.toString("utf8"))), "utf8"); } else { sha.update("rpai/v1/bytes\n"); sha.update(bytes); } return sha.digest("hex"); } ``` ```java // Needs Gson. ImageIO and the rest are the JDK. import com.google.gson.*; import java.awt.image.BufferedImage; import java.io.ByteArrayInputStream; import java.math.BigDecimal; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.*; import javax.imageio.ImageIO; public final class Fingerprint { // disableHtmlEscaping is not optional: Gson escapes <, > and & by default, // and those escapes change the bytes being hashed. private static final Gson GSON = new GsonBuilder().disableHtmlEscaping().create(); public static String of(String fileName, byte[] bytes) throws Exception { String name = fileName.toLowerCase(Locale.ROOT); MessageDigest sha = MessageDigest.getInstance("SHA-256"); if (name.endsWith(".png")) { BufferedImage image = ImageIO.read(new ByteArrayInputStream(bytes)); int w = image.getWidth(), h = image.getHeight(); byte[] pixels = new byte[w * h * 4]; int i = 0; for (int y = 0; y < h; y++) { for (int x = 0; x < w; x++) { int argb = image.getRGB(x, y); // non-premultiplied ARGB int a = (argb >>> 24) & 0xff; if (a == 0) { i += 4; continue; } // fully transparent, four zero bytes pixels[i++] = (byte) ((argb >> 16) & 0xff); pixels[i++] = (byte) ((argb >> 8) & 0xff); pixels[i++] = (byte) (argb & 0xff); pixels[i++] = (byte) a; } } sha.update("rpai/v1/png\n".getBytes(StandardCharsets.UTF_8)); sha.update((w + "x" + h + "\n").getBytes(StandardCharsets.UTF_8)); sha.update(pixels); } else if (name.endsWith(".json")) { JsonElement parsed = JsonParser.parseString(new String(bytes, StandardCharsets.UTF_8)); sha.update("rpai/v1/json\n".getBytes(StandardCharsets.UTF_8)); sha.update(canonical(parsed).getBytes(StandardCharsets.UTF_8)); } else { sha.update("rpai/v1/bytes\n".getBytes(StandardCharsets.UTF_8)); sha.update(bytes); } return HexFormat.of().formatHex(sha.digest()); } private static String canonical(JsonElement value) { if (value == null || value.isJsonNull()) return "null"; if (value.isJsonPrimitive()) { JsonPrimitive p = value.getAsJsonPrimitive(); if (p.isBoolean()) return p.getAsBoolean() ? "true" : "false"; if (p.isNumber()) { double d = p.getAsDouble(); if (!Double.isFinite(d)) return "null"; double r = Math.floor(d * 1e6 + 0.5) / 1e6; // six decimal places, ties up if (r == 0) return "0"; // never "-0" return BigDecimal.valueOf(r).stripTrailingZeros().toPlainString(); } return GSON.toJson(p.getAsString()); } if (value.isJsonArray()) { StringJoiner out = new StringJoiner(",", "[", "]"); for (JsonElement item : value.getAsJsonArray()) out.add(canonical(item)); return out.toString(); } List keys = new ArrayList<>(value.getAsJsonObject().keySet()); Collections.sort(keys); // code-unit order StringJoiner out = new StringJoiner(",", "{", "}"); for (String key : keys) { out.add(GSON.toJson(key) + ":" + canonical(value.getAsJsonObject().get(key))); } return out.toString(); } } ``` ```python # Needs Pillow; everything else is the standard library. import hashlib import io import json import math from PIL import Image def canonical_json(value): if value is None: return "null" if isinstance(value, bool): # before int: bool is an int in Python return "true" if value else "false" if isinstance(value, (int, float)): if isinstance(value, float) and not math.isfinite(value): return "null" r = math.floor(value * 1e6 + 0.5) / 1e6 # six decimal places, ties up return str(int(r)) if r == int(r) else repr(r) if isinstance(value, str): return json.dumps(value, ensure_ascii=False) if isinstance(value, list): return "[" + ",".join(canonical_json(v) for v in value) + "]" return ( "{" + ",".join( f"{json.dumps(k, ensure_ascii=False)}:{canonical_json(v)}" for k, v in sorted(value.items()) ) + "}" ) def fingerprint(file_name, data): name = file_name.lower() if name.endswith(".png"): image = Image.open(io.BytesIO(data)).convert("RGBA") pixels = bytearray(image.tobytes()) for i in range(3, len(pixels), 4): if pixels[i] == 0: # fully transparent, four zero bytes pixels[i - 3 : i + 1] = b"\x00\x00\x00\x00" body = f"{image.width}x{image.height}\n".encode() + bytes(pixels) return hashlib.sha256(b"rpai/v1/png\n" + body).hexdigest() if name.endswith(".json"): body = canonical_json(json.loads(data.decode("utf-8"))).encode() return hashlib.sha256(b"rpai/v1/json\n" + body).hexdigest() return hashlib.sha256(b"rpai/v1/bytes\n" + data).hexdigest() ``` Then walk the uploaded pack and ask about what you found: ```bash curl -X POST https://api.resourcepack.ai/v1/origin/lookup \ -H "content-type: application/json" \ -d '{"hashes":["9f2c1d4a7b3e5f8091a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f708"]}' ``` ```json { "results": [ { "hash": "9f2c1d4a7b3e5f8091a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f708", "verdict": "generated", "form": "png", "kind": "texture", "firstSeen": "2026-08-14T10:22:06.000Z" } ], "matched": 1 } ``` Send up to **256 hashes per call**. Hashes are lower-cased and duplicates collapsed, then every distinct hash gets a result in the order you first sent it. `matched` counts the `generated` ones. ## If you'd rather not tell us what you asked The lookup endpoint means sending us the hashes of files your users upload. If you'd rather not, use the **range** endpoint: send the first five characters of a hash, get back every fingerprint we hold that starts with them, and match the rest yourself. ```bash curl https://api.resourcepack.ai/v1/origin/range/9f2c1 ``` ```json { "prefix": "9f2c1", "suffixes": [ { "suffix": "d4a7b3e5f8091a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f708", "form": "png", "kind": "texture", "firstSeen": "2026-08-14T10:22:06.000Z" } ] } ``` We learn which of about a million buckets you asked about, never which file. ## Rate limits and caching **60 requests a minute per IP address** (there's no key to count against). At 256 hashes a call that is plenty for a review queue. Over budget answers `429` `rate_limited` with the wait in the message. Responses carry `cache-control: public, max-age=60`. ## What the registry holds A hash, which of the three forms produced it, what sort of asset it was, and when it was first seen. **No pack, user, prompt or asset id is stored with it**, so an answer can't reveal anything about who made the file. ## Getting in touch If you're integrating this and something is missing (a batch size, a file form, a webhook instead of polling), tell us. Talk to us [Discord](https://resourcepack.ai/discord) is the fastest route, or [support@resourcepack.ai](mailto:support@resourcepack.ai). --- Source: https://resourcepack.ai/docs/api-reference/rate-limits # Rate limits Requests are counted per **key**, not per IP address, so two teams behind one office connection don't share a budget. There are two budgets, each over a rolling 60 seconds: | Budget | Per key | What spends it | | --- | --- | --- | | Reads | 120 a minute | Every `GET` except export: listing packs and assets, downloading an asset file, polling a job | | Writes | 30 a minute | Every other request (creating a pack, generating, uploading, importing, deleting) and pack export | Unused requests don't carry over to the next minute. Export is the one `GET` that counts as a write, because it builds the pack's `.zip` on demand. The [MCP server](/api-reference/mcp) counts its tool calls against the same two budgets (a tool that reads spends a read, one that changes something spends a write). The [origin check](/api-reference/origin) endpoints are limited separately, per address. `POST /uploads` also has a daily limit: an account can stage 200 uploads a day, across all its keys. Each upload is deleted by the call that uses it. ## Being refused A request over budget answers `429` with the usual envelope and a `Retry-After` header in whole seconds: ```json { "error": { "code": "rate_limited", "message": "Too many requests on this API key. Try again in 24s." } } ``` Wait out `Retry-After` and carry on. Retrying immediately and repeatedly only gets more refusals until the window rolls over. ## Polling inside the read budget A job polled every two seconds is 30 reads a minute, so 120 covers four generations in flight at once. For more than that, poll less often: a model takes minutes, and checking every ten seconds loses nothing over checking every two. See [Jobs and polling](/api-reference/jobs). ## Credits are still the real limit Rate limits stop a runaway loop; they don't limit spend. A generation you can't afford is refused with `402` `insufficient_credits` however slowly you ask, and a generation costs the same whenever you make it. If you're hitting these Both numbers are well above what a working integration needs. Hitting one usually means a retry loop with no backoff, or a poll on a timer rather than after the previous response. If your use genuinely needs more, tell us in [Discord](https://resourcepack.ai/discord). --- Source: https://resourcepack.ai/docs/armor # Armor Armor is what Minecraft draws on a player's body when they wear a helmet, chestplate, leggings or boots. Use it to redraw a vanilla set (every iron helmet looks like yours) or to build a whole new outfit. There are two kinds, picked with the **2D / 3D** switch under **Shape** when you add one: ![Three armor sets made in Studio, worn by a player](/images/armor.webp) - **2D** reskins one of the vanilla sets. Every piece of that set in the world changes, and no plugin is needed. - **3D** builds a new set out of cubes, so a hood can be a hood and a spacesuit can carry its oxygen tank. See [3D Armor](#3d-armor). ## Which sets you can reskin Eight vanilla sets can be reskinned: **Leather**, **Chainmail**, **Copper**, **Iron**, **Gold**, **Diamond**, **Netherite** and the **Turtle Shell**. A pack holds one of each, because a 2D Armor asset *is* the vanilla set it replaces. Sets your pack already has are greyed out in the Add asset sheet. Copper needs 1.21.9, and the turtle shell is a helmet Copper armor arrived in Minecraft 1.21.9, so a pack exported for an older version leaves it out. The turtle shell has no other pieces. ## Making a 2D set This section is 2D Armor; for 3D, see [3D Armor](#3d-armor). Open **Add asset**, choose **Armor**, keep **Shape** on **2D** and pick the set. **Generate**: describe it, for example "weathered bronze scale armor, green patina in the seams". One generation draws the whole set (helmet, chestplate, leggings and boots), so you never make the pieces one at a time. You can attach a **reference image**; the AI uses it to decide where colours and details go on the body (the faceplate, the emblem on the chest). A set takes a few minutes and costs about 45 AI Credits, but it's one charge however many sheets it has. No two runs are alike, so a set that comes back wrong is worth another try. **Blank**: start from **Vanilla art** (the real set, ready to recolour, often the fastest way in) or **Empty**. **Upload**: bring an image. What you get depends on what it is: | You upload | You get | | --- | --- | | A **64×32 armor sheet** (or any image twice as wide as it is tall) | Used exactly as it is | | A **64×64 player skin** | That skin's clothing becomes the armor | | A **character or a piece of armor** on a plain background | Cropped and wrapped onto the body | | **Anything else**, such as a texture or a photo | Tiled over the set, so the armor is made of it | Uploads are free. ### What a generated set covers A generated set follows the shape of the set it reskins. Iron covers what iron covers: a band round the head, sleeves to the elbow, the face bare. That keeps it looking like armor worn over a player rather than a costume. If you want more coverage, paint it in the editor, which has no such limit. Plumes, crests, horns and wings are drawn onto the crown of the helmet, since nothing can stick out past the body's boxes. Why armor looks a size up Minecraft draws each armor box one pixel bigger than the body on every side, so the sleeves and the chest overlap a little. A sleeve a shade different from the chest, or a clear line at the shoulder, keeps the arm reading as an arm. ## Seeing it in game On a server running [RP Engine](/testing/plugin), our free plugin, press **Sync** to send the pack to yourself in game, then choose **Wear in-game** on the set's card (or press **Sync** in the editor): you're dressed in the real vanilla pieces, now showing your art. Without a plugin, [export](/exporting) the pack, apply it, and put on the vanilla armor. Minecraft moved armor textures in 1.21.2. You don't have to think about it: [export](/exporting) writes whichever path your chosen version reads. ## The editor Click a set to open the editor. The flat sheet is on one side and a player wearing it is on the other, and you can paint either. The plain Steve underneath is only there for preview; he never ships with your pack. **Edit with AI**, in the editor, changes the set from a sentence ("make the trim gold", "add a red plume") and leaves the rest as it is. The editor greys out while it runs, and a failed edit leaves the set unchanged. ### How the sheet is laid out Each set is drawn on **64×32** sheets: one shared by the helmet, chestplate and boots, and a separate one for the leggings. The editor hides this from you with one tab per piece (**Helmet**, **Chestplate**, **Leggings**, **Boots**); on a piece's tab the other pieces are dimmed so you can't paint them by accident. The sheet has only one arm and one leg. The game mirrors them for the other side, so painting one boot paints both. Pixels the game never reads are dimmed in the editor. ## Leather and dye Leather is the only dyeable set, and it has two sheets per layer, switched with the **Base** / **Overlay** pill beside the piece tabs: - The **base** is multiplied by the player's dye colour. - The **overlay** is drawn on top and never tinted. Put anything that should take the dye on the base, and anything that must keep its own colour (studs, straps, buckles) on the overlay. A generated leather set paints the base and leaves the overlay empty. Dye can only darken The dye multiplies the base, so it can only make it darker, and there's no way to give each dye colour its own artwork. Draw the base light if you want bright dyes to show. The **Dye** picker in the editor is a preview. The colour lives on the player's item, not in your pack. ## 3D Armor Pick **3D** under **Shape** and describe the set: > an orange chemical suit with a big face window, a breathing tank on the back > and green gloves You get a new set built from cubes: a helmet, chestplate, leggings and boots, each shaped round the body and painted. It has its own name, and a pack can hold as many as you like. You can attach pictures to build one like them. A set takes 15 to 25 minutes and costs about 150 AI Credits, charged for what it actually cost, like a model. Its page lets you orbit it, walk it and raise its arms, which is where a chestplate that's too wide shows up. ### Wearing one in game You need **Minecraft 1.21.4 or newer**. How the set reaches the body depends on the player's version: | Version | How it's drawn | Needs | | --- | --- | --- | | **26.1 to 26.3** | By the game itself, through shaders in your pack. Moves exactly with the body | Nothing: the set's page lists a vanilla `/give` command per piece | | **1.21.4 to 1.21.11** | The helmet by the game; the rest fitted to the limbs by [RP Engine](/rp-engine/armour#3d-armour-from-studio) | RP Engine 0.1.61 or newer | On a server running RP Engine you don't have to choose: **Sync** the pack and press **Give in-game**, and each player sees the set the way their client can draw it. When RP Engine is drawing the body pieces you won't see them on yourself in first person; `/rp armor self` shows them in third person (F5). ### Editing a 3D set Press **Edit armor** on the set's page, or the pencil on its card, to open it in the model editor. Move, resize and rotate cubes in **Edit** mode, and paint them in **Paint** mode, the same way you would a model. A player stands inside the armor so you can see what each piece has to clear. They're only there for reference and aren't saved with the set. Each body part is a group: `head`, `body`, `right_arm`, `left_arm`, `waist`, `right_leg`, `left_leg`, `right_foot` and `left_foot`. A cube moves with the part its group is named after. If you add a cube and don't put it in a group, it goes on the body part it's sitting on. Changes save as you work, like any other editor. **Sync** pushes the set to your server. **Export** downloads the set as a Blockbench `.bbmodel`, with bones named the way MythicArmors expects. ### Importing from Blockbench Drop a `.bbmodel` on the Armor tab's **Upload** door and it becomes a 3D set (a picture still makes a 2D set). Importing is free. Each cube is worn on the piece its group is named after: | Group | Piece | | --- | --- | | `head` | Helmet | | `body`, `right_arm`, `left_arm` | Chestplate | | `waist`, `right_leg`, `left_leg` | Leggings | | `right_foot`, `left_foot` | Boots | Blockbench's own spellings work too (`RightArm`, `Right Arm`), and a cube nested deeper belongs to the nearest body-part group above it. Cubes in no body-part group are left out, and so are meshes. The upload list shows what was found before you import. Build the set around a player standing on the origin: feet at 0, facing south (+Z), right arm on the −X side. That's Blockbench's player template and what Export writes. Save with textures embedded in the file. ## On Bedrock 2D Armor carries over to the `.mcpack` under Bedrock's names for each set, and looks the same on both editions. 3D Armor works for Bedrock players on a server running [RP Engine](/rp-engine) and Geyser, following their arms and legs as they move. Pieces handed out before the server had RP Engine 0.1.66 show as paper; hand them out again. --- Source: https://resourcepack.ai/docs/bedrock # Bedrock and Geyser Bedrock Edition (phones, consoles, Windows) uses a different pack format from Java. Studio converts your pack for you, so you don't make anything twice. How Bedrock players get it depends on where they play. Most Bedrock players reach a Java server through [Geyser](https://geysermc.org/), a plugin that lets Bedrock players join a Java server. If that's you, read the first two rows. | Where they play | What to use | What they get | | --- | --- | --- | | A Java server running Geyser and [RP Engine](/rp-engine), our plugin | Nothing extra. [Sync](/testing/plugin) (sends a pack to you while testing) or [Distribution](/distribution) (sends it to every player) | Everything below, plus placed models with their animations and 3D Armor | | A Java server running Geyser, without RP Engine | **Export › Bedrock players on a Java server** | Custom items with their icons, reskins, Sounds, Armor and chat Icons | | A Bedrock world or Realm | **Export › Minecraft: Bedrock Edition** | Reskins, Sounds, Armor and chat Icons | ## On a Java server with Geyser Geyser translates the game, but it can't read a Java resource pack. Bedrock players need a Bedrock pack, and Geyser needs to be told which Java items are which Bedrock items. Studio makes both. ### With RP Engine If the server runs RP Engine, there is nothing to set up. Each time you press **Sync**, a Bedrock player on the receiving end gets the Bedrock build of the pack; they are disconnected and rejoined for a few seconds, because Bedrock only accepts packs while joining. A pack served with [Distribution](/distribution) always includes the Bedrock build too. RP Engine registers your items with Geyser itself and draws placed models for Bedrock players near them. See [RP Engine › Bedrock and Geyser](/rp-engine/bedrock) for exactly what crosses over. ### Without RP Engine Press **Export** on the pack and choose **Bedrock players on a Java server**. You get one zip laid out like Geyser's own folder: ``` packs/.mcpack the Bedrock pack Geyser sends players custom_mappings/resourcepack-ai-.json which Java items are which Bedrock items README.txt ``` 1. Unzip it into Geyser's folder: `plugins/Geyser-Spigot/` on Paper or Spigot (`plugins/Geyser-Velocity/`, `config/Geyser-Fabric/` and so on elsewhere). 2. Restart the server. Geyser reads packs and mappings only when it starts. 3. Give Java players the Java pack as usual (**Export › Minecraft: Java Edition**, set in `server.properties`). That's it. A custom item is the same item for both editions: the give command on its page works for everyone, and Bedrock players see it with its own icon and name instead of a piece of paper. Not with RP Engine If the server runs RP Engine, leave `custom_mappings/` out. RP Engine registers the same items with Geyser, and two mappings for one item is one too many. The one part worth taking from this zip there is `packs/`, and only if you put the Java pack in RP Engine's `content/` folder by hand: Sync and Distribution send Bedrock players the pack themselves. The same file works whatever Minecraft version your server runs. Keep Geyser up to date, since it uses Geyser's newer mapping format. ## In a Bedrock world or Realm **Export › Minecraft: Bedrock Edition** gives you a `.mcpack`. Open it on any Bedrock device and it imports itself; then turn it on under the world's **Resource Packs**. Without a server there's nothing to hand out custom items or place models, so a world shows the reskins, Sounds, Armor and chat Icons. ## What crosses over | Asset | On Bedrock | | --- | --- | | Block and item reskins | Under Bedrock's own texture names | | Custom items | Their sprite, or a picture of the model, as the item's icon | | Models | Bedrock entities with native animations, placed by RP Engine | | Armor | The same sheets, under Bedrock's names | | 3D Armor | Drawn on the body, with RP Engine | | Sounds | Under your event names | | Icons | Bedrock's glyph sheets, so they work in chat | These have no Bedrock equivalent and are left out: GUI screens, the HUD, Shaders, Text Effects, Dialogs, Emotes, Vehicles, models placed as blocks, per-face block textures and item variants. ### If a reskin doesn't show on Bedrock Bedrock names some textures differently (`golden_apple` is `apple_golden`, `wooden_sword` is `wood_sword`). Studio renames the ones it knows. A reskin of a texture we haven't mapped simply doesn't show on Bedrock; it never breaks the pack. ### If Bedrock's button symbols change Chat Icons replace whole pages of Bedrock's own symbols, and Bedrock keeps a few of its button prompts on those pages. A page holding one of your Icons replaces Bedrock's symbols on it. ## Designing for both If many of your players are on Bedrock, put anything they need to know somewhere that crosses over, such as an item's name and lore, or chat. A menu that only exists as a custom screen, the HUD or a dialog is invisible to them. ## Testing it The [test server](/testing/test-server) runs Geyser: join from Bedrock on the same address and Sync as usual. --- Source: https://resourcepack.ai/docs/blocks # Blocks A Block is a new texture for one of Minecraft's blocks. You pick the block it replaces (stone, oak planks, diamond ore) and every copy of that block in the world shows your art instead. It's the simplest thing to make, and a good first asset. ![Block textures made in Studio, shown on blocks](/images/blocks.webp) A resource pack can only change how existing blocks look. It can't add a new kind of block. If you want something with its own shape, make a [3D Model](/models) instead. ## Making one Open a pack, press **Add asset** and pick **Block**. There are three ways in: - **Generate**: describe it and the AI draws it. - **Blank**: opens the editor with an empty canvas, or a copy of the vanilla block to repaint. - **Upload**: use a PNG you already have. All three ask for the **Block to replace**. Textures that only skin a custom model are made from inside the model editor instead, and replace nothing. Generating with AI How to write a prompt that gives you something worth finishing. ### Size A generated Block is **16×16**, vanilla's own resolution, so it sits naturally next to vanilla blocks. Every generated Block tiles: placed in a wall of itself, it shows no seams. For an "HD" texture with more room for detail, start from **Blank** (16×16, 32×32, 64×64 or any square size up to 256) or **Upload** one. Once you have a draft, the block's page has **Regenerate** (same prompt, new attempt) and **Edit with AI** (describe one change, keep the rest). ### Choosing from 4 versions Every Block you generate is drawn 4 times, and Studio picks the best one to start you off. On Creator, Studio or a Team, the **Versions** card on its page shows all 4: hover over one to preview it, and click it to use it instead. Switching is free, and the one it replaces stays in the Block's AI history, so you can always switch back. On the free plan, the card shows that 4 were drawn. With a reference picture of the thing itself, 2 of the 4 are redrawn from your picture and 2 are drawn from a description of it, in no particular order, so you can pick whichever came out best. ## Seeing it in game The fastest way is **Sync**: on a server running [RP Engine](/testing/plugin) (our free plugin, and [our test server](/testing/test-server) has it), Sync sends the pack straight to you in game, and every copy of that block changes at once. **Give in-game** on the block's page hands you some to place. Without a plugin, [export](/exporting) the pack as a `.zip` and add it to Minecraft like any resource pack. Blocks are worth judging in the world rather than in the editor: a texture that looks great zoomed in can turn into noise in a wall of itself. On [our test server](/testing/test-server), `/floor `, `/time` and `/weather` change what your block sits against. Try it on grass, on white concrete and at night. ## Giving each side its own texture A full-cube block doesn't have to look the same on every side. On the block's page, the **Faces** card shows each face, and each can have its own texture. Click a face to generate it, edit it, or reset it to the base texture. Blocks that vanilla already textures in parts (logs, sandstone, deepslate) show their own parts instead, such as **Top**, **Bottom** and **Sides**. Blocks that aren't simple cubes (stairs, flowers, doors) don't have a Faces card; retexture them as a single texture. **Edit** on a block opens the block editor: a **Block** tab with the block in 3D, plus one tab per face. On the Block tab you paint directly on the cube (drag to paint, drag empty space to orbit). Double-click a face, or click its tab, to open it in the pixel editor. A face's menu has **Apply to all faces**, which copies it onto every side. The block editor saves as you go. Some blocks rotate randomly when placed Stone, dirt, sand, netherrack and a few other natural blocks are given a random rotation each time they're placed, to hide repetition. Their top and bottom are safe, but a distinct north, south, east or west face points a different way on each block. Building blocks (planks, wool, concrete, bricks) don't rotate. ## The pixel editor The pixel editor is where you finish a texture by hand. It opens full screen when you edit a block's texture, and from the model editor when you want to paint a face properly. Items, Icons and HUDs use it too. ### Tools | Tool | Key | Notes | | --- | --- | --- | | Pencil | `B` | Paints the active colour | | Eraser | `E` | Paints transparency, not white | | Fill | `F` | **Connected** fills touching pixels; **Global** fills every pixel of that colour. **Tolerance** sets how close a colour has to be | | Pick colour | `I` | Samples a pixel into the active colour | | Line | `L` | Drag from one point to another | | Rectangle | `R` | Tick **Filled shape** for a solid one | | Ellipse | | Filled or outline, like the rectangle | | Select | `S` | Select a region to move, copy (`Ctrl+C`), paste (`Ctrl+V`) or delete | | Text | `T` | Stamps words in Minecraft's font. They become ordinary pixels | Undo and redo are `Ctrl+Z` and `Ctrl+Y`, and cover layers too. Copy and paste work across Studio: a selection copied here pastes into another texture, a HUD or a font, even in another tab or pack. You can also paste an image copied from outside Studio (a screenshot, or pixels from Aseprite), and a selection you copy here pastes into those programs as an image. The tool options panel also has: - **Brush size**, 1 to 8 pixels. Line and rectangle use it too. - **Alpha** lock, which only paints over pixels that already have colour. - **Mirror X** and **Mirror Y**, which paint the mirrored copy of every stroke. Both together give four-way symmetry. The eraser makes pixels see-through, not white. On a block that should be solid, a transparent pixel shows as a hole, so fill gaps with colour. ### Layers Layers are listed topmost first and flattened when the texture is saved. You can rename them (double-click), reorder, hide and delete them, and nudge or rotate a layer's contents with the arrows under the list. A good habit: keep the AI's draft on the bottom layer and paint your fixes on a layer above it, so you can always go back. The editor saves when you press **Save**. **Export PNG** downloads the image. ## What's in the exported pack In the exported `.zip`, a block texture is a PNG at `assets/minecraft/textures/block/.png`, named after the vanilla block it replaces. Minecraft already looks there, so a plain reskin needs no other files. A per-face block also gets a block model under `assets/minecraft/models/block/` that maps each face to its texture. Studio writes it from the Faces card. The size you worked at is the size in the file. A 64×64 pack installs the same way as a 16×16 one. ## On Bedrock Block reskins carry over to the Bedrock `.mcpack`, renamed where Bedrock calls a block something else (`oak_planks` is `planks_oak`, `white_wool` is `wool_colored_white`). Per-face blocks carry only their base texture. --- Source: https://resourcepack.ai/docs/chat # Chat Chat is the quickest way to make a lot at once. Say what you want in your own words ("make everything ice themed") and it works out what to make: which vanilla blocks to reskin, which items, a GUI, a HUD, sounds. You get a card listing every asset with its price, and nothing is made until you press **Generate**. ## Opening it Press **Chat** at the top of the pack page. It opens beside the pack, so you can watch new assets appear in the grid as they're made. Starting a new pack? Fill in **What should it have?** when you create it. The pack opens with Chat already planning it from what you wrote. ## How it works 1. **Ask.** "Make everything ice themed", "a shop GUI for my server", "rank tags for Member, VIP and Owner". If the pack already has things in it, Chat looks first, so it adds to what's there rather than repeating it. If it needs to know something first, it asks with the answers laid out as buttons: pick one, tick a few, or type the words it needs. 2. **Check the card.** Each asset shows its type, what it replaces, the prompt it will be generated from, and about what it costs. Untick anything you don't want, and press **Edit prompt** to change what it will be made from. 3. **Press Generate.** Each asset is generated exactly as if you'd made it from **Add asset**: the same price, the same refund if it fails, and the same editors afterwards. The card follows each one until it's ready, with a link to open it. You can close Chat while they run. Turn on **Auto-accept**, under the message box, to skip step 3: every new card starts generating as soon as it arrives. You can keep talking after that: "now the tools to match", "make the HUD greener", "what's still missing?". ## What it can make | Type | What Chat proposes | | --- | --- | | **Block** | A reskin of a vanilla block texture. A block with several faces, like grass or a log, gets each of its textures. | | **Item** | A 2D sprite, replacing a vanilla item or as a new one of its own, or a 3D item if you ask for 3D. | | **3D Model** | Handed out as an item or placed as a block. This is how you get a new block of your own. | | **Armor** | A reskin of a vanilla armour set, or a 3D set if you ask for one. | | **GUI** | A chest or menu screen, planned from the description. | | **HUD** | The hearts, hunger, hotbar and the rest, in one look. A pack has one. | | **Dialog** | A Minecraft 1.21.6+ dialog screen: settings, a shop, rules. | | **Icon** | A glyph you can type into chat, signs and books. | | **Rank Tag** | The badge in front of a player's name. Name several ranks for a matching set. | | **Sound** | A sound effect, replacing a vanilla one or as a new event. | | **Shader (2D)** | An overlay drawn on screen, like a health bar or a status panel. See [Shaders](/shaders). | | **Shader (3D)** | An object placed in the world, like a portal or a hologram. | | **Text Effect** | An animated look for chat and menu text, like fire or a rainbow. | | **VFX** | A spell or ability effect, like a slash or a lightning strike. | | **Emote** | A player animation, for one player or several together. | Chat can't make Skins, Vehicles or Mobs: make those from **Add asset**. Chat can also **change things you already have**: ask it to "make the sword red" and it proposes an edit of that asset, run by the same **Edit with AI** button its page has. That works for Blocks, Items, 3D Models, Vehicles, Icons, 3D Shaders, Text Effects, VFX and Emotes. GUIs, HUDs, Dialogs, Armor and Sounds are changed in their own editors. Chat can't delete or export anything, but it can put a **Sync** button in the conversation for you to press. ## Making a whole pack - **Say the look, not just the theme.** "Frozen tundra: pale blue ice, snowy spruce, frost on every edge" gets you pieces that match. Chat writes that look into every prompt. - **It starts with what players see most**: the common blocks, the tools in their hand, the chest screen and the HUD. One card is usually 12 to 16 assets, 24 at most. Ask for the next batch when the first is done. - **3D Models are left out unless you ask.** They take several minutes each and cost the most; a pack is mostly textures. - **Set a Style Guide first** if you want an exact palette: it's the palette button at the top of the pack. Everything generated afterwards, from Chat or not, follows it. ## Pictures Attach up to four pictures to a message with the picture button, by pasting, or by dropping them on the panel. Chat sees them and passes them to the assets that should follow them, the same way a reference image works in **Add asset**. ## What it costs Talking to Chat is free, up to 150 messages a day. Generating uses AI Credits, and the card shows the price of each asset and the total before you press **Generate**. If the total is more than your balance the card says so: untick some, or the last ones won't start. Your conversation stays in this browser Chat keeps the conversation for each pack in your browser, so it's there when you come back. It doesn't follow you to another computer or a private window. **New chat** at the top of the panel starts again; anything already generating carries on. On a pack you were invited to, Chat only offers what your access lets you generate. See [Collaborators](/collaborators). --- Source: https://resourcepack.ai/docs/collaborators # Collaborators A pack starts as yours alone. **Collaborators** are other people you let into it: a builder doing your models, a friend drawing Block textures, a client watching without touching anything. You choose how much each one can do. Collaborators belong to **one pack**. Adding somebody to your castle pack gives them nothing in your other packs. If you want several people sharing every pack and one balance of credits, use [Teams](/teams) instead (they are free). A pack can have **five collaborators** besides you. A pending invitation holds one of those places until it's accepted, declined, withdrawn or expires. ## Inviting somebody Open the pack's Collaborators page Press the people icon at the top of the pack page, beside **Edit** and **Export**. Only the pack's owner sees it. Then press **Add collaborator**. Find them by Minecraft username or email **Minecraft username** works if they have linked their Minecraft account to Studio (see [Linking your account](/testing/test-server#linking-your-account)). **Email** works for anyone, including people without a resourcepack.ai account, who can create one from the invitation. Choose what they can reach **Editor** can do nearly everything: edit, generate, test in game and export. **Viewer** can open everything and change nothing. **Custom** lets you pick the sections and capabilities below. Send it They get an email, plus a Discord message and a line of in-game chat if they've turned those on. Invitations last **14 days** and can be withdrawn from the same page. Inviting by email always says "invitation sent", whether or not the address has an account, so the box can't be used to find out who has signed up. Collaborators never see each other's email addresses; they appear as a Minecraft name and head. ## What a collaborator can do With **Custom** you make two separate choices: which parts of the pack they see, and what they can do there. So "can generate but can't touch my Models" is possible. **Which sections**, matching the tabs on the pack page: Models, Vehicles, Mobs, Blocks, Items, Armor, GUIs, HUD, Dialogs, Icons, Sounds, Emotes, Shaders, and Distribution. A section they aren't given simply isn't there for them. **What they can do in those sections:** | Capability | Lets them | | --- | --- | | **Edit** | Create, edit, rename and delete assets by hand | | **Generate with AI** | Run AI generation and edits, which spend AI Credits (see below) | | **Sync & test in game** | Send the pack to their own game with **Sync**, and use the in-game buttons | | **Export** | Download the pack as a `.zip` or export single models | | **Publish to servers** | Update the pack your live server hands its players ([Distribution](/distribution)), pause it or rename a server | **Publish to servers** is never part of Editor. Give it by name with Custom when you want someone to be able to update a live server. Some things stay yours whatever you grant: renaming, deleting or duplicating the pack, changing its icon, moving assets to or from other packs, choosing whose credits it spends, and managing collaborators. ## Whose credits get spent Generating costs AI Credits. By default a collaborator spends yours. Change it in **Edit pack**, under **AI Credits for this pack**: | Option | What happens | | --- | --- | | **Use my credits** (default) | Whatever a collaborator generates comes out of your balance | | **Everyone uses their own** | Collaborators spend their own credits. Yours stay untouched | Either way your billing history records who ran each action. On a team pack this setting doesn't apply to team members, who spend the team's credits unless they have chosen to [use their own](/teams#using-your-own-credits). ## Testing as a collaborator **Sync** sends the pack into Minecraft for **whoever pressed it**. So a collaborator links their own Minecraft account (see [Linking your account](/testing/test-server#linking-your-account)) and Sync lands on them, not on the pack's owner. To test on their own server instead, each collaborator pairs with their own code (see [The plugin](/testing/plugin)). ## Hearing about what they do **Notifications** on the Collaborators page chooses what you're told about and where, by email, Discord message or in-game chat (the same channels as [generation notifications](/generating#getting-told-when-its-done)). Set it for the whole pack, or override it per person from the gear beside their name. | Event | On by default | | --- | --- | | Adds something | | | Edits something | | | Deletes something | Yes | | Runs AI generation | Yes | | Syncs to Minecraft | | | Exports the pack | | | Accepts collaboration invite | Yes | Every event is sent as it happens, so turning on **Edits something** for a busy collaborator means a message per save. ## Changing or removing access The gear beside a collaborator's name opens their grant, so you can change what they reach. **Remove from pack** ends their access and their sync code for the pack straight away. Anything they made stays in the pack. --- Source: https://resourcepack.ai/docs/dialog-engine # Dialog Engine Dialog Engine is a server plugin for Minecraft's dialog screens: the real menus the game has had since 1.21.6, with text, items, text boxes, dropdowns, switches, sliders and buttons. You write a dialog in YAML, and the plugin opens it, fills it in for each player and runs whatever its buttons say. ![A settings screen drawn by Dialog Engine](/images/dialog-engine.webp) - **Server owners** write dialogs in a folder and give them commands, permissions, conditions, lists and actions. No code. - **Developers** ship dialogs with their own plugin, add their own actions, placeholders and lists, and hear every press of a YAML dialog's buttons as an event. A dialog is drawn by the game itself, so it needs no resource pack. The one exception is a [drawn dialog](#drawn-dialogs), which is a picture designed in the browser and comes with a small pack of its own. Dialog Engine or RP Engine? [RP Engine](/rp-engine/dialogs) has dialogs too, but the two plugins don't share or sync them: a Dialog Engine dialog opens with `/de open`, an RP Engine one with `/rp dialog`. Use Dialog Engine when dialogs are all you need, or you want text boxes, conditions, lists and a click event in Java. For a screen with a mouse pointer written in HTML, see [MC GUI](/mcgui). [Which plugin for menus](/plugins#which-plugin-for-menus) compares them all. ## Installing Get the jar Download Dialog Engine from [SpigotMC](https://www.spigotmc.org/resources/139513/). Drop it in Put the jar in `plugins/` and restart. It runs on **Spigot, Paper or Folia 1.21.7 or newer** (one jar for all three; Folia since 0.7.0) and needs **Java 21**. Players need a 1.21.6 or newer client. [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) is optional. On an older server the plugin says so in the console and turns itself off. Look at what it made ``` plugins/DialogEngine/ config.yml AI-GUIDE.md ← the format, written for an AI assistant dialogs/ ← your dialogs samples/ ← working examples drawn/ ← drawn dialogs samples/ ``` What talks to the internet `update-check` asks SpigotMC for the latest version. `telemetry` sends an anonymous count every 30 seconds: a random id, the number of players online and the names of plugins that depend on Dialog Engine. Both can be turned off in `config.yml`. [Drawn dialogs](#drawn-dialogs) also go online: `/de edit`, and a `dialog.yml` you edited by hand, send that one dialog to the editor to be drawn. Plain YAML dialogs never leave the server. ## Your first dialog Make a file `plugins/DialogEngine/dialogs/myserver/hello.yml`: ```yaml hello: command: hello title: "Hello" body: - "Welcome, {player}. There are {online} of us online." buttons: - label: "Thanks" actions: - "[message] Have fun!" - "[close]" ``` That is the dialog `myserver:hello`: the folder is the namespace and the key is the name. Reload Run `/de reload`. It says how many dialogs loaded and lists every problem it found, with the file each one is in. Open it Type `/hello`, or `/de open myserver:hello`, which works on any dialog whether it has a command or not. Writing dialogs with an AI `plugins/DialogEngine/AI-GUIDE.md` is rewritten on every start. It is the whole format plus the rules that catch the usual mistakes. Hand it to an AI assistant along with what you want the screen to do. ## Where dialogs live Every folder in `dialogs/` is a **namespace**, and every top-level key in a `.yml` file inside it is a **dialog**: `welcome` in `dialogs/samples/menus.yml` is `samples:welcome`. Subfolders stay in the same namespace. Files directly in `dialogs/` are in the namespace `server`. - Names are lower case: `a-z`, `0-9`, `_`, `.` and `-`. The same name twice in one namespace is reported, and the later one wins. - When one dialog names another (`[open] confirm`, `if-missing: pick`), a name without a namespace means one in the same namespace. - Text is [MiniMessage](https://docs.advntr.dev/minimessage/format.html) (``, ``, `<#3670f8>`), never `&` codes. - Quote any string that starts with `<`, `[`, `{`, `%` or `*`, or contains `: `, or YAML will read it as something else. ## The format A complete dialog, a shop with a slider: ```yaml shop: command: shop # /shop opens it (optional) aliases: [store] permission: myserver.shop # who may open it themselves (optional) title: "Shop" columns: 2 # buttons side by side body: - "You have %vault_eco_balance% coins." # a line of text - item: diamond # an item, with words beside it name: "Diamond" description: "A coin each" inputs: - key: amount type: slider label: "How many" min: 1 max: 64 step: 1 initial: 16 buttons: - label: "Buy" tooltip: "Buy {amount} diamonds" actions: - "[if] %vault_eco_balance% >= {amount}" # stop unless they can pay - "[console] eco take {player} {amount}" - "[console] give {player} diamond {amount}" - "[message] Bought {amount} diamonds." - "[close]" exit: # the button Escape also presses label: "Close" ``` ### Dialog keys | Key | What it does | |---|---| | `title:` | The heading | | `external-title:` | A shorter title for where the game names the dialog outside it, such as a button that opens it | | `command:`, `aliases:` | A command that opens it. See [Its own command](#its-own-command) | | `permission:` | What a player needs to open it themselves | | `args:`, `if-missing:` | Command arguments that become placeholders, and the dialog to open when one is left out. See [A dialog about somebody](#a-dialog-about-somebody) | | `defaults:` | Starting values, as `key: value` | | `type:` | `notice`, `confirmation`, `multi_action` (or `menu`) or `links`. Leave it out and the buttons decide | | `columns:` | Buttons side by side. Default 2 | | `escape:` | Whether Escape closes it. Default `true` | | `pause:` | Whether it pauses a single-player game. Default `false`. Ignored with `after: none` or `seamless` | | `after:` | What happens on screen when a button is pressed: `seamless`, `wait`, `close` or `none`. See [After a click](#after-a-click) | | `body:` | What is drawn above the inputs. See [Body](#body) | | `inputs:` | See [Inputs](#inputs) | | `buttons:`, `exit:` | See [Buttons](#buttons). `exit:` is the bottom button, which Escape also presses | | `lists:` | Rows the dialog can repeat over. See [Lists and pages](#lists-and-pages) | | `json:` | Send a file of the game's own dialog JSON instead. See [Raw JSON dialogs](#raw-json-dialogs) | ### Types The layout follows the buttons. One button and no `exit:` is a notice (a notice with no button at all gets the game's Ok button). More buttons make a grid, `columns:` wide, with the `exit:` button under it. For a yes/no screen, write `confirm:` and `cancel:` in place of `buttons:` (or say `type: confirmation`). `type: links` is the game's server links screen. ```yaml rules_decline: title: "Decline the rules?" escape: false body: - "You can't play here without accepting them." confirm: label: "Leave" actions: ["[console] kick {player} You need to accept the rules to play."] cancel: label: "Read them again" actions: ["[back]"] ``` ### Body A body entry is a string (one line of text) or a map: | Key | What it does | |---|---| | `text:` | MiniMessage. A list is several lines. `width:` 1 to 1024, default 200 | | `item:` | An item id, drawn with `description:` beside it. Also takes `name:`, `lore:`, `amount:`, `model:` (an item model id), `custom-model-data:`, `glow:`, `tooltip:` (`false` turns off its hover tooltip), `decorations:` (`false` hides its count and durability bar), and `width:`/`height:` 1 to 256 | | `head:` | A player's name, drawn as their head | | `if:` | Only drawn when this holds. See [Conditions](#conditions) | | `for-each:` | Drawn once per row of a list. See [Lists and pages](#lists-and-pages) | ```yaml body: - head: "{target}" width: 24 height: 24 description: "Tell us what {target} did." - text: - "1. Be kind." - "2. No cheats." width: 260 ``` An item from ItemsAdder, Nexo, Oraxen or your own resource pack is drawn as itself with `model:` or `custom-model-data:`, the same way the plugin gives the real item: ```yaml body: - item: paper model: nexo:ruby # its item model - item: paper custom-model-data: 1001 # a custom model data number - item: paper custom-model-data: # or the game's own lists, by name floats: [1001] strings: ["{gem}"] # placeholders are filled first ``` ### Inputs | `type:` | Keys | What `{key}` holds | |---|---|---| | `text` | `max-length`, `initial`, and `lines` and `height` for a text area | What was typed | | `options` | `options:`, a list of `{id, text, initial}` (or `- id: Text`), or a `for-each` | The chosen `id`. `{key.label}` is its text | | `toggle` | `initial`, `on-true`, `on-false` | `true` or `false`. `{key.text}` is `on-true` or `on-false` | | `slider` | `min`, `max`, `step`, `initial`, `format` (a translation key) | The number | Every input needs a `key:` of letters, digits and `_`, and also takes `label:`, `label-visible:`, `width:` and `if:`. A text input can be checked with `required: true`, `min-length:`, `pattern:` (a Java regex the whole value must match) and `error:` (the message). When a button is pressed and a check fails, the dialog is drawn again with the typed text still in it and the message on top. The message is also `{error}`, so the dialog can print it where it likes. A button with `validate: false` skips the checks, which suits a Cancel button. The `exit:` button never checks. ```yaml inputs: - key: reason type: options label: "Reason" options: - { id: cheating, text: "Cheating", initial: true } - { id: chat, text: "Chat abuse" } - key: details type: text label: "What happened?" lines: 3 height: 48 max-length: 200 required: true min-length: 10 error: "Tell us a little more: at least 10 characters." ``` What a player typed is escaped wherever it is printed, so nobody can put a colour or a click into somebody else's screen. ### Buttons | Key | What it does | |---|---| | `label:` | Its text | | `tooltip:` | Shown on hover | | `width:` | 1 to 1024, default 150 | | `permission:` | Hidden from a player without it | | `if:` | Only shown when this holds | | `for-each:` | One button per row of a list | | `validate:` | `false` skips the input checks | | `id:` | A name for [your own plugin](#events) to recognise it by | | `actions:` | What it does. See [Actions](#actions) | A button that does one thing can use a shorthand instead of `actions:`: `command:`, `console:`, `open:`, `url:`, `copy:`, `suggest:`, `message:`, `close: true` or `back: true`. ```yaml buttons: - label: "Warps" open: warps - label: "Website" url: "https://example.com" - label: "Close" close: true ``` ## Actions A button's `actions:` run in order. A line without a `[tag]` is a command the player runs. | Action | What it does | |---|---| | `[player] cmd` | The player runs it, with their own permissions | | `[console] cmd` | The console runs it | | `[message] text` | Tells the player | | `[broadcast] text` | Tells everybody | | `[actionbar] text` | Shows it above the hotbar | | `[title] title \| subtitle` | Shows a title | | `[sound] id [volume] [pitch]` | Plays a sound: `[sound] entity.experience_orb.pickup 1 1.4` | | `[open] id [key=value ...]` | Opens another dialog, carrying this one's values and inputs over | | `[back]` | Returns to the dialog this one was opened from, as it was | | `[refresh]` | Draws this one again, with what was typed still in it | | `[page] next\|prev\|first\|last\|N` | Turns the page of a paged list | | `[set] key=value ...` | Sets a value for the actions after it, and for any dialog opened | | `[clear] [keys]` | Forgets what was typed: every input, or the keys named | | `[close]` | Closes the dialog | | `[delay] ticks` | Waits before the rest. 20 ticks is a second | | `[if] condition` | Stops here unless it holds | | `[permission] node` | Stops here unless the player has it | | `[stop]` | Stops here | | `[url] link` | Opens a link | | `[copy] text` | Copies to the clipboard | | `[suggest] /cmd` | Puts a command in the chat box, ready to finish | | `[event] id` | Nothing by itself: it names the click `id` for [your plugin's](#events) `DialogClickEvent`. Placeholders work: `[event] buy_{row.id}` | | `[myplugin:tag] ...` | Whatever another plugin registered | `[url]`, `[copy]` and `[suggest]` are the game's own button actions, so they only work as described when they are a button's **only** action. Mixed with others, `[url]` sends the link in chat instead, and `[copy]` and `[suggest]` do nothing. ### After a click What the screen does the moment a button is pressed is the dialog's `after:`, or `default-after` in [config](#config) when it does not say: - `seamless` (the default): the dialog stays exactly as it is until the plugin answers. The next dialog replaces it with nothing in between, and if none follows, the plugin closes it. A button that runs a command closes the dialog first, unless a later action opens another, so a screen that command opens (a chest, another plugin's menu) is not closed by mistake. - `wait`: the game's "Waiting for Server" screen until the plugin answers. A dialog with a `[url]`, `[copy]` or `[suggest]` button behaves as `close`, since the server never hears those being pressed. - `close`: closes at once, then opens the next dialog, if any. - `none`: stays as it is. End a button with `[close]` to leave the screen. ### Typed values in commands A `[console]` or `[player]` command only takes a typed value (a text input, a command's `args:`, values from `/de open`, `{player_display}`) when it is letters, digits, `_`, `.` and `-`: a name, a number, an id. Anything else (`@a`, a space, a quote) and the button runs nothing. A text input is drawn again with the `unsafe-value` message, otherwise the player gets it in chat, and the console names the placeholder. This is checked before the first action runs, so a click never stops halfway. When more than that is safe, say how the value is used: | Filter | What it does | |---|---| | `{key\|raw}` | As typed, on one line. For the last, free-text argument of a plugin's command: `staffchat {player}: {details\|raw}`. Not for vanilla's `say`, `msg` or `tell`, which read `@a` in it | | `{key\|json}` | Escaped for the inside of a quoted JSON string: `tellraw @a {"text":"{msg\|json}"}` | | `{key\|snbt}` | Escaped for the inside of a quoted SNBT string: `give {player} paper[custom_name='{name\|snbt}']` | Values from the dialog itself, from plugins and PlaceholderAPI, and from sliders, toggles and dropdowns (only options the dialog drew count) are not checked. ### When a command fails If a `[console]` or `[player]` command fails, the actions after it do not run. For `[console]` the player sees `command-failed` and the console logs it. The server can only tell a command failed when it does not exist (its plugin is missing) or throws an error. A command that ran and refused, like `eco take` without the money, counts as a success. So **check before taking anything**, as the shop above does with `[if] %vault_eco_balance% >= {amount}`. ## Placeholders `{name}` works in titles, text, labels, tooltips, actions and conditions. A name nothing knows is left as written. Values come from: - what the dialog was opened with: `/de open shop Steve coins=40`, an API call, a command's `args:`, `defaults:`, or an `[open]` or `[set]` action - everything typed into its inputs, once a button is pressed - the built-ins below - whatever a plugin registered, as `{prefix_key}` (see [For developers](#for-developers)) | Placeholder | Value | |---|---| | `{player}` | The player's name (also `{player_name}`) | | `{player_uuid}` | Their UUID | | `{player_display}` | Their display name, as plain text | | `{player_world}` | The world they are in | | `{player_x}` `{player_y}` `{player_z}` | Their block position | | `{player_health}` | Their health, rounded up | | `{player_level}` | Their experience level | | `{player_gamemode}` | `survival`, `creative`, `adventure` or `spectator` | | `{online}` | Players online | | `{max_players}` | The server's player limit | | `{dialog}` | This dialog's id | With [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) installed, every `%placeholder%` works in the same places. A `%` in what a player typed is never filled, so nobody can type a placeholder into a text box to read somebody else's. **Choices.** `{mode?on:Enabled|off:Disabled|Unknown}` prints the words for the value `mode` has, or the last entry when none matches. A `*` entry matches any value that is not empty (`{nick?*:Has a nickname|None}`). `$value` prints the value itself: ```yaml - "Chat: {chat?true:on|false:off|$value}" ``` ## Conditions `if:` works on a body entry, an input and a button. `[if]` is the same thing as an action. ``` {muted} true unless empty, false, 0, no, off or null !{muted} {warnings} >= 3 {rank} == admin && perm:server.staff ({page} > 1 || {mode} != "quiet mode") ``` - `==`, `!=`, `>`, `<`, `>=` and `<=` compare. Two numbers compare as numbers, anything else as words, ignoring case. - `&&`, `||`, `!` and brackets combine them. - `perm:node` is whether the player has that permission. - A placeholder nothing could fill counts as false. - Quote a value with spaces in it. - A condition that cannot be read (a bracket never closed, two values with nothing between them) counts as false, and the console says why once. A button's `if:` and `permission:` are checked again when it is pressed, so a button that stopped applying after the dialog was drawn does nothing. ## Lists and pages `for-each: name` on a body entry, a button or an input's `options:` repeats it once per row of a list. Inside it: - `{row.field}` is a field of the row. `as:` renames `row`. - `{row.index}`, `{row.first}` and `{row.last}` say where in the list it is. - `per-page: N` pages the list and sets `{page}`, `{pages}`, `{has_next}` and `{has_prev}`. `[page] next` turns the page. `limit: N` caps how many rows are shown. | Built-in list | Fields | |---|---| | `online_players` | `name`, `uuid`, `world`, `ping` | | `other_players` | The same, without the player looking | | `worlds` | `name`, `players`, `environment` | Vanished players stay hidden from whoever cannot see them. A dialog can declare its own lists under `lists:`, and plugins can register more. ```yaml warps: title: Warps lists: places: - { id: spawn, name: "Spawn" } - { id: arena, name: "Arena" } buttons: - for-each: places label: "{row.name}" actions: ["[player] warp {row.id}", "[close]"] ``` A paged list of players, eight to a page: ```yaml players: title: "Online ({online})" body: - "Page {page} of {pages}" buttons: - for-each: online_players per-page: 8 label: "{row.name}" tooltip: "{row.world} · {row.ping}ms" actions: ["[open] player_card target={row.name}"] - label: "← Previous" if: "{has_prev}" actions: ["[page] prev"] - label: "Next →" if: "{has_next}" actions: ["[page] next"] exit: label: "Close" ``` ## Opening a dialog ### Its own command `command: shop` makes `/shop` open the dialog, and `aliases:` adds more names. They come and go with `/de reload`, no restart needed. With a `permission:`, a player without it is refused and does not see the command in tab completion. A command name another plugin already has stays that plugin's, and the console says so. ### A dialog about somebody `args: [target]` makes `/punish Steve` open the dialog with `{target}` set to `Steve`, and tab completion offers online players. The last argument takes the rest of the line, so `args: [target, reason]` reads `/punish Steve being rude` as `Steve` and `being rude`. `if-missing:` opens another dialog when an argument is left out, usually a list of players to pick from: ```yaml report: command: report args: [target] if-missing: report_pick title: "Report {target}" # ... report_pick: title: "Who are you reporting?" buttons: - for-each: other_players label: "{row.name}" actions: ["[open] report target={row.name}"] ``` ### The Quick Actions key Minecraft 1.21.6 added a Quick Actions key, **G** unless a player rebinds it. `quick-action: true` puts a dialog on it. With several dialogs on the key, G shows a list of them to pick from. ```yaml menu: title: "Menu for {player}" quick-action: true # G opens the dialog itself # ... shop: title: "Shop" quick-action: mode: launcher # G opens a button that opens the dialog fresh label: "Shop" # what the key's list calls it (default: the title) # ... ``` The key is the player's game, not the server: pressing it opens a copy of the dialog the player was sent when they joined, and the server is never told. So there are two modes: - **direct** (the default, also `true`). G opens the dialog straight away. Dialog Engine draws each player's copy for them as they join, so `{player}`, a head, and PlaceholderAPI values (a LuckPerms rank, say) show what was true at that moment, and stay that way until they join again. Its buttons work as usual. The player is not in a world yet when it is drawn, so placeholders about where they are or their health are empty, and a button with a `permission:` is left out. `DialogOpenEvent` is not fired: the server does not know it opened. - **launcher**. G opens a small screen with an **Open** button (its words are `messages.quick-open` in config.yml), and the button has the server open the dialog, drawn fresh like any other: every check, placeholder and event as usual. One extra click, and nothing is out of date. Direct needs Paper. On Spigot, and for a dialog with a `permission:` or a `json:` dialog, G opens the launcher instead. A drawn dialog goes on the key with `quickAction: true` in its `dialog.yml` (or the editor's Quick Actions switch), and opens directly too; `quickAction: launcher` keeps the launcher, and a drawn dialog showing the player's own items always uses it. While a drawn dialog is on the key, players are sent the drawn dialog pack as they join, so it is ready before they first press G. The key only picks up a change after a **restart**: what G opens is part of the data the server reads as it starts, written to `world/datapacks/dialogengine_quick`, and the console says when a restart is owed. Nothing extra is downloaded. ### From the console, or for somebody else ``` /de open [player] [key=value ...] ``` `/de open samples:report Steve target=Alex` opens the report on Steve's screen, about Alex. Opening a dialog this way skips its own `permission:`; only `dialogengine.open` (and `dialogengine.open.others` for another player) count. The console and command blocks always name a player. From another dialog, `[open] id` carries every value over, and `[back]` returns to the first one as it was. The target dialog's `permission:` is still checked. ## Raw JSON dialogs For something the game's dialog format can do and this YAML cannot, `json: file.json` (a file beside the YAML) sends a `minecraft:dialog` object exactly as written, with `{placeholders}` filled. Its buttons do whatever the JSON says, and none of Dialog Engine's actions or checks apply to them. ## Drawn dialogs A plain dialog uses the game's own widgets. A **drawn dialog** is a picture: a screen designed in Studio's [dialog editor](/dialogs) in the browser, in the game's look or any other, and shown with a small resource pack. Its buttons still run Dialog Engine's [actions](#actions), and placeholders, PlaceholderAPI values and the player's own inventory are filled in as it is opened. ``` /de edit server:shop_drawn ``` That prints a link to the editor, which needs no account. The link works once and lasts three hours. Draw the screen, press **Send to server**, and it is written into `plugins/DialogEngine/drawn/server/shop_drawn/` and loaded. Run `/de edit` on it again to change it. You can also download a dialog from the editor's **Export** menu for Dialog Engine, unzip it into `plugins/` and run `/de reload`. - `/de edit` only draws. A YAML dialog is edited in its file, and the command says so. A name without a namespace is in `server`. - Each drawn dialog's folder has a `dialog.yml` with its `command:` and `commandPermission:` at the top. You can edit it by hand and `/de reload`: a changed file is sent to the editor to be redrawn, which needs the internet. A command on a drawn dialog reads `{name}` from the same places its words do, PlaceholderAPI included: `{vault_eco_balance}` is `%vault_eco_balance%`. On a list, a row's command gets what that row showed when the dialog opened, so `party invite {player_list}` invites the player whose name is on the row, even if the list has changed since. That holds for every button a row can have (**Run command**, **Run as console**, several commands) and however the list is filled: by PlaceholderAPI, by a plugin, or when opening, as in `/de open server:warps Steve warps=Spawn,Shop`. A list given when opening is typed text, so an item goes into a command only when it is letters, digits, `_`, `.` and `-`. A drawn dialog's pieces fire [`DialogClickEvent`](#events) too. A piece has no `id:`, so name it in its command: in the editor, **When clicked** set to **Run command**, with `[event] claim`. Your plugin then answers every piece of a menu in one listener, and the event carries the player's settings with it. You can also register an action and name it there, `[myplugin:claim] daily` (or several, `[a] ...; [b] ...`). A command with no brackets is run by the player, as on any dialog. ### Settings A switch, slider, dropdown or segmented control in a drawn dialog can be bound to a **setting**: a name like `hud_quest_tracker`. Each player has their own value, kept on the player, so it is still there after they log out or the server restarts. Clicking the control changes it and the dialog redraws. - Inside the dialog, `{hud_quest_tracker}` is the player's value. - Anywhere else, with PlaceholderAPI, it is `%dialogengine_setting_hud_quest_tracker%` (see [PlaceholderAPI](#placeholderapi)). A scoreboard, a chat format or another plugin's config can read it there. - A plugin reads it with [`setting(player, name)`](#for-developers). Until a player clicks the control, the setting reads as the choice the dialog shows first, so `visible` rather than nothing. A dialog drawn before Dialog Engine 0.7.2 has no default saved: run `/de edit` on it and press **Send to server** once to add it. ### PlaceholderAPI With [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) installed, Dialog Engine answers these anywhere PlaceholderAPI is read: | Placeholder | Value | |---|---| | `%dialogengine_setting_%` | The player's value for a drawn dialog's setting, or its default until they set it | | `%dialogengine_var_%` | The same, spelled the way RP Engine spells it | | `%dialogengine_open%` | `true` when the player has a dialog open | | `%dialogengine_dialog%` | The id of the dialog they have open, or nothing | | `%dialogengine_value_%` | A value of the dialog they have open, such as what they typed into an input | | `%dialogengine_can_open_%` | `true` when they may open that dialog | | `%dialogengine_dialogs%` | How many dialogs are loaded | | `%dialogengine_version%` | The plugin's version | A setting no dialog declares is printed as written, so a typo shows rather than reading as an empty value. Dialog Engine does not need RP Engine for any of this. If you also run RP Engine, the two keep their settings apart: a dialog Dialog Engine shows saves to `%dialogengine_setting_…%`, and one RP Engine shows saves to `%rpengine_var_…%`. The same goes for Dialog Engine's own [actions](#actions). **Open another dialog** takes only an id, so to open one with values, set **Run command** to `[open] studio:shop item=diamond count={amount}`. That is the `[open]` action: the next dialog takes this one's place without closing it first, carries its values over, and `[back]` returns. Running `/de open` from a button instead closes the dialog and opens a new one, so the world flashes in between. ### The resource pack All drawn dialogs share one small pack, which is sent alongside any pack your server already sends, not instead of it. It is only built once you have a drawn dialog, so a server that never uses `/de edit` never asks anybody to download anything. The plugin uploads the pack to ResourcePack AI's free pack host (`packs.resourcepack.ai`) and players download it from there, so there is nothing to open or set up (`pack.host: upload`). It is only uploaded again when it changes, it is kept while your server uses it, and only the Minecraft client can download it. If an upload fails, the plugin serves the pack itself until it works. To serve it yourself instead, set `pack.host: serve`: it is served on port `8165`, and `pack.public-host` must be your server's public address or domain, with that port open. Or host it somewhere else: `/de pack` writes it to a file, and `pack.url` says where you put it. Players with `dialogengine.pack.notify` are told the download address when the pack fails to load for them. ### Other plugins' shaders A drawn dialog that shows a player's head does it by replacing the game's text shader, and some HUD plugins (BetterHud among them) replace the same shader. A player's game keeps only one copy, from whichever pack is highest in their list, so without help one of the two stops drawing. ```yaml shaders: merge: true notify-players: true ``` With `merge: true`, Dialog Engine reads the other plugin's pack from its folder and combines the two shaders inside the drawn dialog pack, so both draw, with no extra pack to download. When it has merged, a joining player's pack waits up to three seconds for the other plugin's to arrive first, so the drawn pack lands on top. If the other plugin's pack arrives later anyway, the drawn pack is sent again, on top. The console says what was merged, on which versions, and what could not be and why. So does chat for players with `dialogengine.shaders` (ops), when it happens and when they join; `notify-players: false` keeps it to the console. ## Samples On first start the plugin writes sample dialogs into `dialogs/samples/`: a welcome notice, server rules, a shop, kits, warps, a player list, a profile, a report form, a settings page with every input type, and a menu of them all, which `/dialog-samples` opens. Two more are drawn dialogs in `drawn/samples/`: a punishment panel (`/sample-punish `) and a six-page social settings menu (`/sample-social`). Their pack is only sent when somebody opens one. Only players with `dialogengine.samples` (ops) can open the samples. They are yours to copy, change or delete. Deleting one file keeps it deleted; deleting the whole folder brings them all back on the next start. `samples: false` in `config.yml` stops them being written. ## Commands `/dialogengine`, with `/de` and `/dialogs` as aliases. `/de` on its own lists the subcommands you can use, and tab completion only offers those. | Command | What it does | Permission | |---|---|---| | `/de list` | Every dialog, by namespace, with its command | `dialogengine.list` | | `/de open [player] [key=value ...]` | Open one, with values | `dialogengine.open` | | `/de info ` | What a dialog is made of: type, buttons, inputs, command, permission | `dialogengine.info` | | `/de edit ` | Draw one in the browser editor, or make a new one | `dialogengine.edit` | | `/de pack` | Write the drawn dialogs' resource pack to a file | `dialogengine.pack` | | `/de reload` | Read everything again and report what is wrong | `dialogengine.reload` | `/dialogclick` is what a click on a drawn dialog runs. It only does what the dialog on that player's screen allows, so it needs no permission and typing it yourself does nothing. ## Permissions Every node is op-only by default. | Node | What it allows | |---|---| | `dialogengine.list` | `/de list` | | `dialogengine.open` | `/de open ` on yourself, for any dialog, whatever its own `permission:` | | `dialogengine.open.others` | `/de open ` on somebody else, on top of `dialogengine.open` | | `dialogengine.info` | `/de info` | | `dialogengine.edit` | `/de edit`. Pressing Send in the editor **writes files into your server's dialog folder**, so grant it with care | | `dialogengine.pack` | `/de pack` | | `dialogengine.reload` | `/de reload` | | `dialogengine.pack.notify` | Being told the drawn dialogs' pack address when it fails to load for you | | `dialogengine.samples` | Opening the sample dialogs | | `dialogengine.update` | Being told on joining that a newer Dialog Engine is out | | `dialogengine.shaders` | Being told when the drawn dialog pack's text shader was merged with another plugin's, or clashes with one | | `dialogengine.admin` | All of the above in one node | A dialog's own `permission:` and a button's are whatever node you write there. Give them out with your permissions plugin as usual: ``` /lp group default permission set myserver.shop true /lp group admin permission set dialogengine.admin true ``` ## Config `plugins/DialogEngine/config.yml`. `/de reload` reads it again. | Key | Default | What it does | |---|---|---| | `samples` | `true` | Write the sample dialogs when their folder is missing | | `update-check` | `true` | Say in the console and on join when an update is out | | `telemetry` | `true` | The anonymous usage count described under [Installing](#installing) | | `click-lifetime-minutes` | `30` | How long a dialog's buttons keep working after it is drawn. Drawing it again restarts the clock | | `default-after` | `seamless` | What a dialog does when a button is pressed, if it has no `after:`. See [After a click](#after-a-click) | | `close-delay-ticks` | `10` | Under `wait`, how long the waiting screen is held for a plugin to answer before it closes | | `click-sound` | `ui.button.click` | The sound a click on a drawn dialog makes. Blank for none. A dialog drawn in Studio can set [its own](/dialogs#click-sounds) | | `validation-format` | `⚠ {error}` | How a failed input check is shown when the dialog does not print `{error}` itself | | `messages.*` | | Everything the plugin says to players, in MiniMessage | | `edit.url` | `https://studio.resourcepack.ai` | Where the dialog editor is. Must be `https://` | | `pack.send` | `true` | Send the drawn dialogs' pack to players as they join | | `pack.required` | `false` | Kick players who decline it | | `pack.host` | `upload` | `upload` to ResourcePack AI's pack host, or `serve` from this server | | `pack.port` | `8165` | The port the built-in pack server listens on (`serve`, or while an upload fails) | | `pack.bind` | blank | The address it listens on. Blank is every address | | `pack.public-host` | blank | The address players download it from: your server's public address or domain | | `pack.url` | blank | Host the pack yourself and put its URL here. The built-in server is then off | | `pack.prompt` | | The line shown when the pack is offered | ## How clicks are kept safe Every button is bound to the dialog the player was shown, with the values it was drawn with. Nothing a player types in chat presses a button. - Only the latest drawing can be pressed. Opening another dialog, refreshing or a failed check retires the old buttons. - A button's `permission:` and `if:` are checked again when it is pressed. - Buttons stop working `click-lifetime-minutes` after the dialog was drawn, and a player gets at most ten clicks a second. - A drawn dialog's clicks work once per showing, only while it is on the player's screen, and only run commands in its `dialog.yml`. ## For developers Add `depend: [DialogEngine]` to your `plugin.yml` (or `softdepend`, and check `DialogEngine.isEnabled()` first) and compile against the jar. The API is in `ai.resourcepack.dialogs.api`, and every call is main-thread only. ```java DialogEngineAPI dialogs = DialogEngine.api(); // Ship dialogs server owners can edit: copy defaults into your data folder, // then register it. /de reload reads it again. saveResource("dialogs/menu.yml", false); dialogs.registerFolder(this, "myplugin", new File(getDataFolder(), "dialogs")); // Open one, with values for its {placeholders}. dialogs.open(player, "myplugin:menu", Map.of("coins", "120")); dialogs.refresh(player); // draw the player's current dialog again dialogs.close(player); // Change what an open dialog says, then draw it once. dialogs.set(player, "coins", "95"); dialogs.set(player, "status", "Bought!"); dialogs.refresh(player); // A new action: [myplugin:give] diamond 3 dialogs.registerAction(this, "myplugin:give", (ctx, arg) -> { String[] p = arg.split(" "); ctx.viewer().getInventory().addItem(new ItemStack(Material.matchMaterial(p[0]), Integer.parseInt(p[1]))); ctx.refresh(); }); // {myplugin_coins} dialogs.registerPlaceholders(this, "myplugin_", (viewer, ctx, key) -> key.equals("coins") ? String.valueOf(economy.balance(viewer)) : null); // for-each: myplugin_quests dialogs.registerList(this, "myplugin_quests", (viewer, ctx) -> quests.of(viewer).stream() .map(q -> Map.of("id", q.id(), "name", dialogs.escape(q.name()), "done", String.valueOf(q.done()))) .toList()); ``` - **Values you pass are read as MiniMessage.** Put anything a player wrote through `dialogs.escape(...)` first. An action's argument arrives with its placeholders filled and typed text as typed, so check it before it goes into a command. - `registerDialog(plugin, "myplugin:x", section)` registers a dialog built in code, as a `ConfigurationSection` in the same format. - `installDrawn(plugin, namespace)` installs drawn dialogs your jar carries under `drawn//` (listed in its `files.txt`), once per version of your plugin. Any the server owner has edited are left alone. - `setting(player, name)` reads what a drawn dialog's switch, slider or dropdown bound to `name` is set to for that player. It is empty until they have set it; `%dialogengine_setting_%` gives the dialog's default instead. - `setSetting(player, name, value)` sets one, as if they had clicked the control, and a null value clears it back to the dialog's default. It fires no `DialogSettingChangeEvent` (that is for a player's own clicks) and draws nothing, so `refresh` afterwards if they are looking at it. It returns false for a name or value a setting can't have. Since 0.8.1. - `set(player, key, value)` changes one value of the dialog a player has open without drawing it, so several changes cost one `refresh`. A null value takes the key away. It returns false when they have no dialog open. Since 0.8.1. - Also: `current(player)`, `isOpen(player)` and `values(player)` for the dialog a player has open, `ids()` and `info(id)` for what is loaded, `canOpen(player, id)`, `textJson(...)` to render MiniMessage the way a dialog does, `unregister(plugin)` and `reload()`. Everything a plugin registers is dropped when it disables. ### Your own items in a drawn dialog A drawn dialog's grid of item slots can show a container "from a plugin", by a name set in the editor: a bank, a shop's stock, a quiver. Register that name and Dialog Engine shows what your inventory holds, each item with its own picture, count and tooltip. If the grid lets items move, the player moves them between your container and their own inventory with two clicks. ```java dialogs.registerContainer(this, "bank", new DialogContainer() { public Inventory inventory(Player viewer) { return banks.of(viewer); } // null: empty slots public boolean mayPlace(Player viewer, int slot, ItemStack stack) { return stack.getType() != Material.BEDROCK; } public void changed(Player viewer) { banks.save(viewer); } }); ``` The inventory stays yours. It is read as the dialog opens and written as each move happens, and a move reads both slots at that moment, so a stale screen cannot duplicate an item. `mayTake` and `mayPlace` refuse a move per slot, and [`DialogSlotMoveEvent`](#events) still fires for every one, with the slot named `api.bank/0`. Since 0.8.1. ### Events | Event | When | |---|---| | `DialogOpenEvent` | A dialog is about to be drawn: opened, refreshed, paged or returned to. Cancellable. `getValues()` can be changed, and `isReopened()` says whether it is the same dialog again | | `DialogClickEvent` | A button was pressed and its inputs passed, before its actions run. Cancellable. `getButtonId()`, `getInputs()` (what was typed, chosen and toggled), `getSettings()` (a drawn dialog's switches, sliders and dropdowns), `getValues()`, `getActions()` (changeable), `isDrawn()`, and `getContext()` to open, refresh or close | | `DialogCloseEvent` | A dialog left the player's screen. `getReason()` says how, `getButtonId()` which button closed it, `getNextDialogId()` what replaced it, and `getValues()` and `getSettings()` what it was left with. See below | | `DialogSettingChangeEvent` | A switch, slider or dropdown on a drawn dialog is about to change a setting. Cancellable: the setting keeps its old value. `getName()`, `getOldValue()`, `getNewValue()` | | `DialogSlotMoveEvent` | A stack is about to move between a drawn dialog's item slots. Cancellable: the items stay put. `getFrom()` and `getTo()` (`inv/5`, `ender/3`...), and copies of both stacks | | `DialogInputErrorEvent` | An input failed its check. The message can be changed | | `DialogEngineReloadEvent` | Everything was read again | A button with an `id:` and no actions is one your plugin answers, and so is any button whose actions name it with `[event]`, which is how a drawn dialog's pieces are named. One listener can run a whole menu: ```java @EventHandler public void onClick(DialogClickEvent event) { if (!event.getDialogId().equals("myplugin:menu")) return; switch (event.getButtonId()) { case "claim" -> rewards.claim(event.getPlayer()); case "save" -> profiles.save(event.getPlayer(), event.getInputs(), event.getSettings()); default -> { return; } } event.getContext().close(); } ``` `DialogCloseEvent` fires once a dialog has gone, whatever took it away. Drawing the same dialog again (a refresh, a page, a setting) is not a close. Its reasons: | Reason | | |---|---| | `EXIT` | The exit button, or Escape, which presses it: `exit:`, a confirmation's `cancel:`, a drawn dialog's Close | | `BUTTON` | A button's actions closed it, or nothing came after them | | `REPLACED` | Another dialog took its place, after that one is on the screen | | `SCREEN` | A chest or other container, the death screen, or another world's loading screen took the screen | | `PLUGIN` | A plugin called `close(player)` | | `QUIT` | The player left | The game tells the server about Escape only by pressing the exit button, so a YAML dialog with buttons and no `exit:` closes with Escape unheard. Give it an `exit:` (it needs no actions) when you need to know. On Folia, a move to another world is not reported either: Folia does not tell plugins about it. ## Support Questions, bugs and ideas: [the ResourcePack AI Discord](https://resourcepack.ai/discord). --- Source: https://resourcepack.ai/docs/dialogs # Dialogs A dialog is a menu screen a server opens on a player: a shop, a settings menu, a warp list, a server guide, a punishment panel. Its buttons run commands, it can scroll, and it looks like part of Minecraft. Studio lets you design one the way you would design an app screen, with sidebars, cards, switches, item slots, pictures and pages. ![A settings dialog made in Studio, open in game](/images/dialogs.webp) Dialog screens were added to Minecraft in 1.21.6. Unlike a chest [GUI](/guis), nothing can be dragged in or out of a dialog, though it can show items with their tooltips and even let a player rearrange their own inventory. ## What you need | | | | --- | --- | | Minecraft | **1.21.6 or newer** on the server and the client. Older versions have no dialog screen; use a [GUI](/guis) there. | | A plugin | [RP Engine](/rp-engine) or [Dialog Engine](/dialog-engine), our free server plugins. They open the dialog and fill in what is different for each player (their name, balance, inventory). A plain datapack also works, with less: see [Without RP Engine](#without-rp-engine). | | The resource pack | Everything drawn on the screen is pictures in your pack, so players need the pack too. | Several features need a recent plugin version: see [Plugin versions](#plugin-versions). ## Making your first dialog Add a dialog to your pack Open a pack, press **Add asset** and pick **Dialog**. Then choose: - **Generate**: describe the screen and the AI designs it. See [Generating one](#generating-one). - **Blank**: start from nothing (a title, a line of words and a **Close** button) or from a **template**: an event shop, a quest board, a server hub, a rank store, daily rewards, a crate, a profile, warps, rules, a welcome screen, an NPC conversation, a battle pass, a podium, a hero offer, a character sheet, a game picker, a level-up screen, a staff console, two ranks compared, a purchase to confirm, a cosmetics shop with tabs or settings with a sidebar. Your dialogs are listed on the pack's **Dialogs** tab. Change it in the editor Click the dialog to open the editor. Double-click words to retype them, drag pieces to move them, and give each button something to do under **When clicked** (the AI leaves that to you). See [Finding your way round the editor](#finding-your-way-round-the-editor). Send it to your server On a server running RP Engine, press **Sync** in Studio. Sync sends your pack (pictures and dialogs together) to you in game, in seconds, without a restart. The first time, it asks you to link the pack to your server: see [The plugin](/testing/plugin). Our [test server](/testing/test-server) already runs RP Engine if you don't have a server yet. Open it In game, run: ``` /rp dialogs # list the dialogs on the server /rp dialog studio:quest-board # open one ``` The dialog's id is shown in its settings panel in the editor. To let players open it themselves, see [Letting players open it](#letting-players-open-it). ### Generating one Say what the screen is for: "a settings menu with video, audio and chat", "a pet menu where you can rename and summon your pet", "a crate menu for a prison server". The AI builds it in the game's own look: plain grey cards, rows of settings with switches, segmented choices, sliders and dropdowns, items and faces. Name a colour for the screen ("a red menu") or use your pack's [Style Guide](/generating#writing-a-prompt) palette to theme it; a colour you name for one thing ("a red Ban button") goes on that thing only. Then it looks at the result as a player would and fixes cut-off labels and screens that are too tall before saving. Kits, banners, motion and the rest of the [textures](#textures) are yours to add in the editor. - A dialog costs **30 AI Credits**. - **Variations** makes up to three dialogs from one prompt, each with a different look, at 30 credits each. - Tick **Multi page** for a sidebar or tabs with a page behind each button, every page written for its name. Name the pages you want in the prompt, up to ten. It costs 30 credits for the first page and 5 for each one after. - Ask for a form ("the player types a reason and picks a length") and it adds [inputs](#inputs). - Numbers on a generated dialog (balances, prices, player counts) are samples for you to change. It names the buttons; you wire them The AI never invents a command. Buttons arrive named and described, with no action, because a command does real things on your server. The exceptions are controls bound to a [player setting](#player-settings) and buttons that turn [pages](#pages), which are wired for you. ## Putting it on your server There are two ways, and you can use both. **Sync, with RP Engine.** Press **Sync** and the dialog opens straight away with `/rp dialog `, no restart needed. RP Engine also writes your dialogs into a datapack, so after the next restart each one also has a real `namespace:id` you can open from a command block or your own datapack. **As files.** The editor's **Export** menu downloads the dialog for a server you don't Sync to, and for [Dialog Engine](/dialog-engine), which doesn't take a Sync (the two plugins don't share dialogs): | Export | Where it goes | | --- | --- | | **Dialog Engine (.zip)** | Unzip into `plugins/`, run `/de reload`, open with `/de open :`. `/de edit` brings it back into Studio's editor. | | **RP Engine (.zip)** | A content folder. Unzip into `plugins/` and run `/rp reload`. | | **Datapack (.zip)** | Every dialog in the pack as `minecraft:dialog` files. See [Without RP Engine](#without-rp-engine). | | **Resource pack (.zip)** | Only the pictures and fonts this dialog uses. | | **Picture (.png)** | The screen at three times its size. | Both plugin downloads carry everything the plugin fills in: live values, inventories, bars, lists, pages and conditions. ### Letting players open it `/rp dialog` is for staff. To let players open a dialog themselves, click the empty space around the screen in the editor and give it a command under **Players open it with**, such as `shop`. Everybody can use it, or only players with a permission you name. `/shop Steve` opens it about Steve, as `{target}`. If another plugin already owns the command, that plugin keeps it. ### Opening it about another player A punish menu is about the player being punished. Write `{target}` (or any name) in the title, words, tooltips or commands, and give its value when you open it: ``` /rp dialog studio:punish target=Steve # open it for yourself /rp dialog studio:punish target=Steve Admin # open it for Admin, about Steve ``` The player to open it for goes last, and opening it for someone else needs `rpengine.dialog.others`. Plugins pass values through [RP Engine's API](/rp-engine/api#dialogs). ### The Quick Actions key Minecraft 1.21.6 added a Quick Actions key, **G** unless a player rebinds it. Tick **Open it with the Quick Actions key** in the dialog's panel and G opens it. Put several dialogs on the key and G shows a list of them to pick from. Pressing G opens a copy of the dialog the player was sent when they joined; the server is never told. So there are two ways to put a dialog on it: - **Opens the dialog** (the default). G opens it straight away, drawn for each player as they join: their name, head and other values show what was true then, until they next join. Buttons work as usual. This needs Paper. On Spigot, and for a dialog behind a permission, G opens the launcher instead. - **Opens a launcher**. G opens a small screen with an **Open** button, which has the server open the dialog fresh. Use this when a dialog shows something that changes, like a balance or a rank. A dialog with the player's own items in it always uses the launcher. Either way, the key only picks up a change when the server **restarts**. ### Without RP Engine A dialog is a vanilla `minecraft:dialog`, so a datapack alone can run one. Put the **Datapack** export in your world's `datapacks/` folder, restart, and open it with `/dialog show @s studio:`. Players still need the resource pack, either the whole pack or the dialog's own **Resource pack** export. To add that to a pack of your own, load it as a separate pack, or copy its files in and merge any `assets/minecraft/font/default.json` into yours rather than overwriting it. Its `README.txt` lists which character is which picture. The **Datapack** export puts a dialog that is on the Quick Actions key on the key as well, and G opens it as written. Without a plugin, everything per player is missing: live values show as written, bound controls stay on their default, inventories, live heads, bars and lists are empty, conditions are ignored, and `/rp` commands do nothing. Page turns and **Close the dialog** still work. The **minecraft:dialog** tab lists which of these a dialog uses. ## Finding your way round the editor Everything on a dialog is a **piece** (Studio also calls them components): a button, some words, a card, a row that holds other pieces. The screen sits in the middle, the list of pieces (**Components**) on the left, and the selected piece's settings on the right. The screen behaves like the game: the mouse wheel scrolls, hovering shows tooltips, and **Clickable areas** (`A`) shades where a click will land. **It is the size your game makes it.** Set your **Monitor** and **GUI scale** with the monitor button at the right of the bar above the screen (the same as *Options › Video Settings › GUI Scale*) and the editor works out the screen the way Minecraft does, so you see whether the dialog fits or scrolls. **Zooming.** The editor opens zoomed on the dialog itself, as big as fits while keeping its pixels sharp. `=` and `-` (or **Ctrl** and the mouse wheel) zoom, `0` fits the dialog again, and the tools on the left also fit the whole screen or show **Game size**, every pixel as big as in game. Hold **Space** (or the middle mouse button) and drag to move round the screen. **Adding.** **+** (or `N`) opens **Add component**: shelves of pieces, and a search box across all of them: | Shelf | What is on it | | --- | --- | | **Blocks** | Ready-made groups: settings card, setting row, sidebar (plain, of cards or of buttons), tab bar, button stack, card list, profile card, stat cards, product grid, yes or no, header bar, and a [List](#lists-the-server-fills). | | **Decor** | Banner, hero item, rarity card, ribbon, ornament and glow dividers, window, fade card, big lettering, sparkles and confetti. See [Changing how it looks](#changing-how-it-looks). | | **Items** | Item slot, grid of slots, your inventory. See [Items and inventories](#items-and-inventories). | | **Controls** | Switch, segmented, slider, dropdown, checkbox, stepper, search box, text box, sidebar button, icon button, theme button, list option, badge. | | **Basics** | Text, heading, big title, button, link, icon, player head, pack glyph, chip, check line, label and value, progress bar, page of text, QR code, divider, space, an image of your own, and a drawing. | | **Layout** | Row, column, grid, card, plain card, tray. | The piece follows your pointer and a yellow bar shows where it will land. Click to place it, hold **Shift** to keep placing, or press **Enter** to put it after the selection. **Editing.** Click a piece on the screen or in **Components**. Its panel lists its words first, then what clicking it does and its tooltip, then its look. Double-click any words on the screen to type straight onto them. Drag the blue grips to resize, and double-click a grip to go back to fitting the content. The bar under the screen (**Screen › Card › Row › Button**) selects any parent in one click. **Moving.** Drag a piece to move it between rows and columns. Hold **Shift** while dragging, or use **Place anywhere**, to lift it out of the layout and put it at any pixel; it snaps to edges and centres (hold **Alt** not to). **Back into the layout** returns it. With one placed piece selected, **Ctrl**-click others to select them too: the panel lines them up by their edges or middles, or spreads them with even gaps, and the arrow keys and Delete act on all of them. **Shortcuts.** Right-click a piece for **Edit words**, copy, paste, duplicate, **Group in a column**, **Put on a panel**, **Ungroup** and delete, or use `Ctrl+C`, `Ctrl+X`, `Ctrl+V`, `Ctrl+D`, `Ctrl+G` and `Ctrl+Shift+G`. Pieces paste into your other dialogs too, even in another tab. `Ctrl+Z` undoes and `Ctrl+Shift+Z` or `Ctrl+Y` redoes. Changes save on their own. Press `?` (or the keyboard button at the bottom of the tools) for every shortcut. **Finding a piece.** Type in **Find a piece** above **Components** to show only the pieces whose kind, name or words match, with the boxes they are in. The arrows beside **Components** open or close every box at once. **The dialog's own settings.** Click the empty space around the screen (or press Escape) for: **Title** (and whether the game shows it), **Players open it with**, the live values it uses, **Content width** (160 to 388 pixels, with a note on which screens it fits), **Theme**, tooltip style, **Click sound**, **Footer** (**One button**, **Yes / No** or **None**), **Inputs**, and **Behaviour** (**Escape closes it**, **Pauses singleplayer** and [After a click](#after-a-click)). **JSON** shows the layout, and its **minecraft:dialog** tab shows the file the game reads. **Export** downloads the dialog for a plugin, a datapack or as a picture (see [Putting it on your server](#putting-it-on-your-server)), and, for a dialog with [motion](#motion), a [floating piece](#floating) or an [animated picture](#animated-pictures), as an **Animated GIF** for a store page or a post. **Edit with AI**, on the page strip, changes what is on a page. It costs 15 AI Credits and `Ctrl+Z` takes it back. **Export as PNG**, on a piece's right-click menu, saves that piece as images for dialog plugins that build screens from pictures: the art without words, a lit version for buttons, a `.slice` file giving the columns that must not stretch, and previews with the words drawn on. ## What you can put on it A dialog is up to 388 pixels wide and about 1,000 tall. Pieces sit in rows, columns and grids, and when the dialog is taller than the player's screen, the game scrolls it. These are the pieces you can add: | Piece | What it is | | --- | --- | | **Button** | The game's grey button, the theme's button or the GUI's light panel one, in its own colour if you like. Its icon can be [a picture of your own](#pictures-in-buttons-and-bars). See [Button looks](#button-looks). | | **Link** | Clickable words, for a contents list. | | **Text**, **Heading**, **Big title** | Words in the game's font, or [one of your own](#your-own-fonts). Colour codes work: `&a` green, `&c` red, `&6` gold, `&e` yellow, `&b` aqua, `&7` grey, `&l` bold, `&r` reset, `7ff55` any colour. | | **Page of text** | `# Title`, `## Heading`, `### Heading` (gold), `- bullets`, `> notes`, `**gold words**`, `---` for a rule. | | **Icon** | Any vanilla item, a player head, your pack's own sprites and textures, one of more than a hundred drawn icons (the **Small** shelf of the picker has nine-pixel ones for labels), or one of your own pictures (the **Pictures** shelf). Bare or in a slot. | | **Image** | A PNG, JPG, GIF or WebP up to 512 pixels a side. Add it from **Add component** or drop the file on the screen. An animated GIF, or several pictures chosen at once, [plays in game](#animated-pictures). It is kept with the pack for its other dialogs. To put a picture *behind* other pieces, give their box a [Picture](#a-boxs-own-look). | | **Drawing** | A picture you draw in the editor. See [Drawing a picture](#drawing-a-picture). | | **Chip**, **Badge**, **Check line**, **Label and value** | A balance or tag; a small solid tag such as NEW; a ✔ or ✘ line; a label left and a value right. | | **Progress bar** | A label, a count and a bar, in its own **Bar colour** and **Track colour** if you like. **Icon before the label** puts a small icon at the start of its line. It can [follow the player](#bars-that-follow-the-player). | | **Controls** | Switch, segmented (two to four choices), slider, dropdown, checkbox, stepper, search box and text box, drawn in the theme. They are pictures unless bound to a [player setting](#player-settings); players can [type in a text box](#typing-in-a-drawn-box). | | **Sidebar button**, **List option**, **Icon button**, **Theme button** | The parts of a settings screen. A sidebar button can be taller than its 18 pixels, carry a badge, and show [a picture of your own](#pictures-in-buttons-and-bars). | | **Item slots** | See [Items and inventories](#items-and-inventories). | | **QR code**, **Divider**, **Space** | A QR code opens its link when clicked. A divider runs the length of its box, or takes a **Length** in pixels (drag its handle, or set it in its panel); placed anywhere, it keeps its length. | ### Button looks Under **Look** in a button's panel: | Look | What it does | | --- | --- | | **Selected** | Draws it lit (gold on the game's button, the accent on the theme's): "you are here", or a card's main action. | | **Greyed out** | Draws it grey with faded words and icon, like a disabled button in the game. It only changes the picture: a click still runs its action, so set **When clicked** to **Nothing** if it shouldn't do anything. | | **Words from the left** | Starts its label at the left edge rather than centred, for a sidebar of buttons. | A **Theme button** also has a **Style**, in its **Texture** section: **Pill** (round ends), **Chunky** (a thick lip under it, a little taller: the big action), **Glossy**, **Stripes**, **Checks**, **Dots**, **Fade**, **Outline** (hollow, for a Cancel beside a chunky Buy), **Notched** (corners cut, for sci-fi screens) or **Price tag**. Each draws in the button's colour, or the accent when it is selected. Some [textures](#textures) dress their theme buttons in a style of their own; a style you pick wins. These are drawn into the dialog's picture, so a plugin can't switch them as the dialog opens. To show a button lit or greyed for some players only, draw it both ways and let [Show when](#show-when) choose, on a permission, a [player setting](#player-settings) or a [live value](#live-values) your plugin sets. ### Drawing a picture **Add component** › **Drawing** starts a blank picture as wide as the dialog, drawn with the same tools and colours as the texture editor. Set its size on the right (one pixel per pixel of the dialog) and press **Done** to place it. - Every text, rectangle, ellipse, line and paste lands on a layer of its own. The **Move** tool (`V`) picks one by clicking it; the arrows nudge it and Delete removes it. - Text stays editable: its words, font (Minecraft, Classic, Small Caps, Tiny, Block or your pack's own), size, colour, fade or rainbow, bold, italic, underline, strikethrough, shadow, outline, alignment and spacing. - **Turn into pixels** lets you paint over text. **Draw on it**, in any image's panel, opens a drawing again with its layers as you left them. ### Pictures in buttons and bars Anything with an icon can show one of your own pictures instead: a button, a sidebar button, a tab, a chip in a header bar, a card heading. In its **Icon** picker, open **Pictures** and choose one, or **Import a picture…**. The picture is fitted whole into the icon with its shape kept: a small one is scaled up by whole steps so pixel art stays sharp, and a big one is shrunk smoothly. An icon is 16 pixels, which is small for a picture. A button or a sidebar button can draw it bigger: set **Icon size** in its panel to 24, 32 or 48 and the button grows to hold it. A sidebar of picture buttons is a **Sidebar** from **Blocks** with a picture and a size on each entry. For a picture *beside* the buttons, such as a logo at the left of a top bar, drop an **Image** into the bar's row. For one *behind* a whole bar, give the bar a [Picture](#a-boxs-own-look). ### Your own fonts Anything with words on it can be set in a font of your own: a text, a button, a tab, a sidebar button, a chip, a badge, a checkbox, a dropdown and the rest. Open **Font** in its panel and choose **Upload a font (.ttf)**, or pick one the pack already has. Fonts are kept with the pack and shared with its GUIs, HUDs and rank tags. - **One piece**: **Font** in that piece's panel. - **Everything in a box**: **Font** in the box's panel. Every piece inside it uses that font unless it has one of its own. - **The whole dialog**: **Font** in the dialog's own panel, under Theme. It applies on every page. The words are drawn into the dialog's picture, so players never need the font and it works on every server. A piece grows to hold a font taller than Minecraft's. #### Other alphabets Minecraft's own font, as Studio draws it, has Latin letters and symbols only. For words in Thai, Chinese, Japanese, Korean, Russian, Greek and so on, upload a font that has those letters. You don't have to pick it on every piece: - Words with no font chosen are set in the first font of the pack that has their letters. Type Thai into a button and it is drawn in your Thai font. - A letter the chosen font doesn't have is taken from another font of the pack that has it. - The oldest font in the pack is tried first, so adding a font never changes what is already drawn. With no font in the pack that has a letter, it is drawn as `?`. #### The details - **Files**: TrueType (`.ttf`) or a collection (`.ttc`), up to 32 MB each, up to 16 per pack and 64 MB together. That is room for Chinese, Japanese and Korean fonts, which are 5 to 20 MB. An `.otf` with PostScript curves can't be read; use the font's `.ttf` version. - **Sizes**: a pixel font is drawn exactly at its own size (the editor detects it) or at 2x or 3x. Any other font is drawn at the size you choose, best at 10px or more. - **Missing letters** are drawn in the other case, then without their accent, then in Minecraft's own font, then in another font of the pack. So a font with no English letters still works, with accents and tone marks stacked correctly. Thai and Chinese wrap between letters. - **Not supported**: scripts written right to left, or whose letters join up (Arabic, Hindi). - Colour codes still work. **Bold** is only what you tick: a heading keeps the font's own weight. - **What the game draws stays in Minecraft's font**: the title, the footer buttons, tooltips, boxes players type in, and words holding a [live value](#live-values). The game has every alphabet itself, so these show correctly in game. The editor's preview draws letters it doesn't have as `?`. ### Tooltips Anything clickable can have a tooltip, written as plain lines: ``` Tuesday - Free Reward ∙ 250 Coins Click to claim! ``` The first line is the title. A line above a list of `∙` items is its heading, lines starting ✔ are green, ⌀ or ✘ red, and "Click" yellow. Colour codes work too. The dialog's tooltip setting changes the box, rim and colours for the whole dialog, or takes them **From the theme**. A footer button's tooltip always keeps the game's box, and a slot of the player's own inventory shows the item's real tooltip. A tooltip can hold [live values](#live-values), filled in for each player: `You have {coins} coins`, or a PlaceholderAPI placeholder written either way, `{vault_eco_balance}` or `%vault_eco_balance%`. **Insert a live value** under the tooltip picks one. An item slot's name and lore take them too. A tooltip holds up to 2,000 characters. A live value counts as one, however long its name is. ## Making buttons do things Anything can be clickable: a button, an icon, a card, an item slot. Select it and choose what it does under **When clicked**. The buttons along the bottom of the screen, below your picture, are the **footer**; they are the game's own buttons and are set the same way. ### What a click can do | Action | What happens | | --- | --- | | **Run command** | The player runs it, with their own permissions. One command per line: [several](#several-commands-on-one-button) run in order. | | **Run as console** | The server runs it as the console, so the player needs no permission for it. `{player}` is who clicked. See below. | | **Suggest command** | A small box opens with the command typed in; they finish it and press **Run**. (Minecraft does not let a dialog fill the chat box.) | | **Open link** | The game asks before opening it. Must start with `http://` or `https://`. | | **Copy text** | Copies it to their clipboard. | | **Go to page** | Turns to another [page](#pages), or makes a new one. | | **Close the dialog** | Closes it, for an X or a Cancel you drew yourself. | | **Open another dialog** | Opens one of the pack's dialogs straight away. **Another id…** takes any dialog id the server already knows. On Dialog Engine 0.6.1 and newer that includes Dialog Engine's own dialogs, by their id (`shop:main`) or by the name of one in the same folder (`main`). | | **Nothing** | Only shows the tooltip. On a footer button, it closes the dialog. | **Run as console** is for a command only the dialog should give them: `warp spawn {player}` from a menu, without everybody having `/warp`. It is safe: the command never reaches the player's game, and the server runs it only for somebody whose dialog has that button, so typing it in chat does nothing. It can't use what the player typed into a text box. ### Several commands on one button **Run command** and **Run as console** take one command per line, up to 16, and run them top to bottom with one click: ``` give {player} bread 8 give {player} torch 16 tellraw {player} "Here you go" ``` Minecraft lets a click run only one command, so the plugin runs a button with more than one. - **They stop at the first that fails.** A command the server does not know, or one that errors, ends the list there. - **Several "Run command" lines cannot use what the player typed** (`$(name)`): a typed value only ever reaches a single command, so only the first line runs. A single "Run command" line can. - **In the vanilla datapack download** only the first command runs, because there is no plugin there to run the rest. Minecraft refuses a whole dialog if one action is invalid, so a button with a bad link, a bad id or an empty command is sent with no action, and the editor marks it until you fix it. The game finds a click by the 9-pixel line of text it lands on, so a clickable piece is clickable on every line it covers at least half of. **Clickable areas** shows the real shape. ### After a click Under **Behaviour**, choose what the dialog does once something is clicked: | Choice | What happens | | --- | --- | | **Seamless** (default) | Stays on screen until the server answers. A dialog the click opens replaces it without a flash, and otherwise it closes. In a datapack it acts as **Close**. | | **Close** | Closes at once, so the next dialog arrives after a glimpse of the world. | | **Stay open** | Stays open. After a **Run as console** button, or a **Run command** button with several lines, it's drawn again so live values and **Show when** catch up with what the commands changed. | | **Wait** | Shows the game's "Waiting for Server" screen. A dialog with a link or copy button closes instead. | A seamless dialog stays open after a click the server never hears, such as a link or a `/server` command on a proxy. Escape closes it. Dialogs with pages always stay open. ### Click sounds The game makes no sound for a click on the drawn screen, so the plugin plays one. **Click sound** in the dialog's settings is **The game's click** (with pitch and volume), **Another sound** (one of your pack's or the game's), or **Silent**. Any clickable piece can override it with **Its own**. Clicks that never reach the server (links, copy, pages that turn instantly) make no sound, and footer buttons always make the game's click. The server-wide default is `dialogs.click-sound` in RP Engine's [configuration](/rp-engine/config#dialogs) and `click-sound` in Dialog Engine's. ### Inputs A dialog can ask for something with Minecraft's own text box, checkbox, list or slider, drawn under the screen and above the footer. Add them under **Inputs** in the dialog's settings. Each has a **Key**, and a footer button's command can use `$(key)`: ``` ban {target} $(length) $(reason) ``` A checkbox gives `true` or `false`, and a choice written `7d=7 days` shows "7 days" and gives `7d`. Only footer buttons fill in keys. A text box can be shorter: switch off **Show its label** to drop the line of words over it, and switch on **Compact** for a box 17 pixels tall rather than 20. A compact box is one line that does not scroll, so it holds as much as its width does. ### Typing in a drawn box A **Text box** from the **Controls** shelf is a picture of a box until you switch on **Typing** in its panel. Then players click it and type in it, and what they typed reaches a footer button's command under the key in **Saved as**, like any input: ``` block $(player) ``` Studio sets the game's own text box exactly on your drawn one and hides the game's look of it. The game writes what players type, in light grey from the box's left edge, so a dark theme reads best. Where the game puts its box is the game's choice, and the editor follows it: - **The box is always centred.** A text box as wide as its card lines up by itself. One off to the side is marked in amber with where the game will put it; **Line it up** in its panel moves it there. - **A second box goes 10 pixels under the first**, a third 10 under that. - **The first box ends the clickable part of the dialog.** Nothing beside or below it can be clicked, so the button that sends the answer goes in the footer. Words and pictures below it are still drawn. - **Leave Longest answer empty** unless you need a limit. A box is one line and takes as much as fits across it, and once it is full players can type no more: the panel tells you about how many letters that is. A limit is never more than that, so the game's count under the box (such as `3/16`) reaches its end when the box is full. The editor draws the same count. For longer answers, make the box wider. It lines up exactly on Minecraft 1.21.11 and newer. On 1.21.6 to 1.21.10 the game puts its box 4 pixels higher, so what is typed sits at the top of the drawn box. ## Changing how it looks The look is set at three levels: the **texture** is what the whole dialog is made of, the **colours** tint it, and any piece can be given a texture of its own. Everything here is drawn into the picture, so it needs nothing on the server. ### Textures A dialog's texture is what everything is drawn with: the material the cards are made of, how round their corners are, their frame, the dividers, how headings are lettered, and whether lit things glow. Pick one in the dialog's **Texture** section: | Texture | Looks like | | --- | --- | | **Classic** | The plain raised cards, in any colours. | | **Scroll** | Parchment in a gilded frame, wax-red accents. | | **Luxe** | Near-black velvet with gold trim and glowing highlights. | | **Glass** | Dark glass with bright corner brackets and scanlines. | | **Wood** | Warm planks and cream words. | | **Frost** | Pale ice with soft corners. | | **Forge** | Cracked rock with glowing seams. | | **Arcade** | Black with neon outlines. | | **Meadow** | Leafy green and sunshine gold. | | **Castle** | Grey stone bricks and gold. | | **Toy** | Flat grey plastic, round corners and a chunky shadow, for friendly hubs and tutorials. | | **Night** | A starry sky. | | **Comic** | Bold black ink outlines, printed dots and sunny colours, with chunky buttons. | | **Terminal** | A green-on-black screen with scanlines and hollow buttons. | | **Tide** | Rolling water with coral gold and pill buttons. | | **Blossom** | Soft pink with drifting petals and pill buttons. | | **Regal** | Royal purple cloth in a gold frame, with glossy buttons. | A texture comes in its own colours, and you can change them under **Theme** without losing the texture. Changing texture never moves anything: every piece keeps its place and size. On a dialog with [pages](#pages), each page can have a texture and colours of its own. **Texture for** and **Colours for** say where a change goes: **This page** changes only the page you have open, **Every page** changes them all. While every page shares one look, a change goes to every page; once a page has its own, it goes to that page only, and **Use this page's look on every page** puts them all back in one. ### Surfaces and colours Any box can sit on a surface, chosen under **Behind it**: the theme's **Card** (with or without a **Heading band**), a sunk **Tray**, a highlight **Band** behind one row, the GUI's light **Panel** or **Dark panel**, an item **Slot**, or the see-through **Shade**, **Deep shade** and **Gold**. Tick **Clicking** on a row or column to make the whole box one button. Cards, controls and highlights are drawn in the dialog's colours. Pick one of fourteen under **Colours** (Stone, Slate, Deepslate, Nether, Ocean, Jungle, End, Royal, Oak, Parchment, Ice, Cherry, Redstone, Sand), or choose any **Card** and **Accent** colour and the rest is worked out from those. What they are drawn *with* is the [texture](#textures). ### A piece's own texture Every piece that can have one has a **Texture** section in its panel, closed until you open it. A row, column or card's **Look** section says what it is drawn on and its own **Fill**, in a colour of its own, fading down or across to a second one (words on it take colours that read on it). Its **Texture** holds the rest: - **Picture**: an image behind the box's content, cropped to fill it, with **Darken for words** so a title reads over it. Choose one of your images, one of the **Starter banners** (free), or **Draw it with AI**: describe a scene and the image model paints it at exactly the box's size (10 AI Credits). - **Made of**: planks, parchment, stone, bricks, velvet, glass, frost, magma, leaves, metal, stars or grid. - **Corners**, **Border** (thin or thick), **Bevel**, **Drop shadow**, **Glow**, **Corner ornaments** (gold, brackets or rivets) and **Opacity**. A **Banner** from the **Decor** shelf is a box like this, ready-made: a picture across the top with its title lettered over it, a line under it and a chip at its right. Its art prompt is already in its panel, ready to draw. ### Lettering, glows and decorations - **Lettering** on a text piece: an **Outline**, letters that **Fade** to a second colour, and a **Shadow** colour or none. **Huge** and **Giant** sizes draw words three and four times their size. - In an icon's **Texture**: **Glow** puts a soft halo behind it, and **Burst of rays** a ring of rays, for the thing to look at. It can **Sit in** an item slot, or a **Round**, **Diamond** or **Gem** socket rimmed in its glow colour (or the accent), for rewards, products and portraits. **Outline and shadow** gives an item a dark outline and a soft shadow, so it reads like a polished sticker on any card. - In a badge's **Texture** it can be a **Ribbon** with notched ends, and in a divider's an **Ornament**, **Glow**, **Fade** or **Dots** line. - A **Decoration** scatters sparkles, stars, confetti or hearts over its box. Place it anywhere, over a banner or round a reward. Words that hold a [live value](#live-values) are drawn by the game, so they keep its font and take no lettering. ### Motion Any piece can **shimmer** (a shine sweeps across it), **pulse**, **twinkle**, cycle through the **rainbow** or **flicker** like candlelight, slowly, normally or fast. Set it under **Motion** in the piece's panel; everything inside the piece moves with it. The editor plays it as it will look, and the pause button on the left stops it while you work. In game it is played by your resource pack, so it needs nothing from the plugin: a player with the pack sees it move, from the moment the dialog opens. The parts the game draws itself (live words, player heads, inventory items) stay still. ### Floating Any piece can **float**: it bobs gently up and down over whatever is behind it, by one to three pixels, slowly, normally or fast. Set it under **Floating** in the piece's panel. Everything inside the piece floats with it, and motion on it still plays. Pieces side by side bob out of step, so a row of floating items doesn't move as one block. ### Animated pictures An **Image** can play. Import an animated GIF, or choose (or drop) several pictures at once and they become the frames of one animation, in name order (`frame_1.png`, `frame_2.png`…), at 10 frames a second. A GIF keeps its own timing. One faster than 30 frames a second, or with more frames than fit, plays fewer frames over the same length, and one bigger than 254 pixels a side is scaled down. The picker marks an animated picture with its number of frames. Floating pieces and animated pictures are played by your resource pack, like motion: nothing is sent while they move, and the editor and the pause button show them as they will look. Two things stay still, and the piece's panel says so when it happens: - a piece drawn differently for each player, or inside one: anything with a [Show when](#show-when) or other colours under a condition, a control bound to a [player setting](#player-settings), a row of a list, a sorted box; - a piece with something the game draws itself inside it: live words, a live player head, an inventory slot, a bar that follows the player. Each frame is a picture in your pack, so a long, large animation makes the pack bigger. ### Text effects on words If your pack has [text effects](/text-effects), a text piece's **Text effect** puts one on its words: a wave, a rainbow, fire. The game draws those words, in its own font, and your pack's shader plays the effect. ### A Close in the dialog's style The game's grey footer button looks the same on every dialog. **Draw it in the dialog's texture instead**, under **Footer**, hides it and puts a button that closes the dialog just under the content, which you can move and restyle. Most templates start that way. ## Pages A dialog can have up to 99 pages, for a settings screen with a sidebar, a store's categories or a guide's chapters. A dialog generated with **Multi page** already has them. To add pages yourself, the quickest way is to select a sidebar button: its panel offers **A page for every button**. **Create pages** gives each button its own page. The box beside the sidebar becomes the part that changes from page to page (outlined in green), and everything outside it stays the same on every page. - The **Pages** strip above the screen has a tab per page. Double-click to rename; the first tab is where the dialog opens. **+** adds a copy of the current page. - Edits outside the green outlines change every page; edits inside one change only this page. Tick **Changes from page to page** on more boxes, such as the info under a sidebar as well as the content beside it, and each changes from page to page on its own. - A button that goes to a page lights up on that page by itself. - **Show on pages**, in any piece's panel, leaves it off the pages you untick, even outside the green outline: a balance in the sidebar that the home page already shows elsewhere. Its space stays empty there, so nothing else moves when the page turns. - **Edit with AI** redraws the page you are on, either only its own part (when it has one) or the whole screen. In game each page is its own dialog: `studio:settings`, then `studio:settings.audio` and so on. A dialog with pages stays open when clicked, so pages turn without flashing the world, and keep the values the first page was opened with. After a server restart, pages with nothing per player on them turn instantly; `/rp dialogs` says which. ## Showing each player their own screen A dialog can be different for every player who opens it: their name and balance in the words, their own settings on the switches, their inventory in the slots, a VIP button only VIPs see. The plugin fills all of this in as the dialog opens, so everything in this section needs RP Engine or Dialog Engine on the server. In the editor you see a sample: default settings and every permission held. ### Live values Write a name in curly braces, like `{player}`, and it is filled in for each player: `Coins: {coins}` shows their balance, `Punish {target}` names the player the menu is about. Live values work in the title, the words on the screen, tooltips, footer buttons and the commands clicks run. Select some words and open **Insert a live value** to pick one. | Placeholder | What it is | |---|---| | `{player}`, `{displayname}` | Their name, and their name with any prefix | | `{health}`, `{health_max}`, `{health_percent}` | Health | | `{food}` | Hunger, out of 20 | | `{level}`, `{xp}` | Experience level, and percent to the next | | `{xp_points}`, `{xp_needed}` | Points into this level, and what the level takes | | `{air}` | Seconds of breath left | | `{ping}` | Latency in milliseconds | | `{world}`, `{x}`, `{y}`, `{z}`, `{direction}` | Where they are | | `{time}`, `{day}` | The world's clock and day count | | `{gamemode}` | Their game mode | | `{online}`, `{max_online}` | Players online, and the cap | | `{uuid}` | Their UUID | Any other name works too. The first of these that has a value wins: 1. Values the dialog was opened with (`name=value` on `/rp dialog`, or from a plugin). 2. The player's own [settings](#player-settings). 3. Values a plugin set for the player with `overlays().set(...)`, the same ones [shader object](/shaders#live-values) labels show. 4. The built-in list above. 5. PlaceholderAPI, if installed: `{vault_eco_balance}` or `%vault_eco_balance%`. A placeholder with arguments works as you would write it anywhere else, `%server_time_HH:mm%` or `%stat_{player_name}%`, and is handed to PlaceholderAPI exactly as written. It can't have a space in it. A name nothing answers is shown as written. A placeholder can choose between words: `{show_sidebar?on:Shown|off:Hidden}`, where the last choice is used when no other matches. Live words stay on one line (press Enter in them for a new line), and a value too long for its space is cut short with "…". Characters the game's small font cannot draw, such as Chinese or emoji, show as "?". **A player's face.** In a **Player head**'s icon picker, choose **Whoever opens it** (`head:{player}`) or **Who it is about** (`head:{target}`), and the game draws that player's own skin. This needs Minecraft 1.21.9 or newer; the editor shows Steve. A head given a username instead is fixed to that player's skin at the time you saved. ### Player settings A switch, segmented control, slider, stepper, checkbox or dropdown is normally just a picture. Give it a name under **Player setting** in its panel (lower case, like `show_sidebar`) and it becomes a real control: it shows each player's own setting, and clicking it changes their setting and redraws the dialog. Settings are kept per player across restarts, with no setup. Your own plugins and commands can then read them, so a settings screen actually changes something. A dropdown opens into a list of its options when clicked (upward, if it is near the bottom of the dialog), and picking one sets it and closes the list. Clicking the dropdown again, or any other control, closes the list without picking. A slider moves its knob to wherever you click on its track; its arrows step it one position at a time. A slider or stepper can show a setting with at most 21 positions, so 0 to 100 needs a step of 5 or more. With more than that it stays a picture, and its panel says so and suggests a step. A setting with more options than fit on one segmented control can be split across several: give each the same **Player setting**. Each one lights up only when the setting is one of its own options, and shows nothing chosen otherwise, so a choice of eight names can be two rows of four. A player who has never picked one gets the first control's default. Only segmented controls share a setting this way (not the cycle look); for any other control, the first one with that name is the one that works. A segmented control or dropdown shows its choices as you typed them. To show something else, tick **Show something else for each choice** under **Shown as**, and a box appears for each choice. Colour codes work there (`&c`, `&l`, `[b8b2`), so the choices `Human` and `Demon` can be shown as `[b8b2Human` and `&#ff2424Demon`. Pick one of your pack's fonts under it to draw them all in that font. The setting still stores the choice itself (`human`, `demon`), so commands, conditions and `{character_race}` never see the colours. An empty box shows the choice as it is. Other plugins read a setting through PlaceholderAPI, by the plugin that shows the dialog: `%dialogengine_setting_show_sidebar%` on [Dialog Engine](/dialog-engine#placeholderapi), `%rpengine_var_show_sidebar%` on RP Engine (or through [RP Engine's API](/rp-engine/api#player-settings)). The two plugins keep their settings apart. Inside the dialog, `{show_sidebar}` is its value. A player can only set a setting to a value some dialog on the server offers. ### Bars that follow the player A **Progress bar**'s value and most can be live values, so it shows each player's own progress. The **Follow** shortcuts set both at once: | Follow | Value | Most | |---|---|---| | Hearts | `{health}` | `{health_max}` | | Hunger | `{food}` | `20` | | Progress to the next level | `{xp}` | `100` | | Experience points | `{xp_points}` | `{xp_needed}` | | Breath underwater | `{air}` | `15` | | Health, as a percentage | `{health_percent}` | `100` | Any value works, such as `{kills}` out of `100`. Commas and `%` are ignored, so `1,250` and `75%` read fine, but a value that is not a plain number (including `1.2k`) leaves the bar empty. The editor draws a live bar 60% full. A bar can also stand up, as a gauge: set its **Direction** to **Up** to fill from the bottom, or **Down** to fill from the top (a tank draining, a time running out). A standing bar has no words of its own, so put a label or an icon beside it, and it can fade from its **Bar colour** at the bottom to a **Top** colour. A live one needs RP Engine 0.2.2 or newer, in either direction. ### Lists the server fills A **List** (on the Blocks shelf) is one row repeated for each item the server gives it, up to twelve: the player's homes, the warps, friends online. In the row, `{warps}` is each row's own value and `{warps_note}` a second field of it. Empty rows are hidden, but their space is kept, so put a list at the end of a card. Fill it when opening: ``` /rp dialog studio:warps warps=Spawn,Shop,Arena ``` or from a plugin with `dialogs().list(...)` or `listRows(...)` (see [the Plugin API](/rp-engine/api#dialogs)), with each row's button running, for example, `warp {warps}`. Switch the list to **Repeated a number of times** when the server knows how many but not what each is called. **How many** can be a number, or a live value such as `{home_slots}`. Then the list's own name is the row's number: a button `Home {home}` running `home {home}` reads *Home 1*, *Home 2* and so on. **Scrolling a list.** A list starts at its first item unless you change **Start at** in its panel. Give it a number, or a [player setting](#player-settings) such as `{warps_from}`, and bind a stepper to that setting: each step moves the list, so a list of thirty warps can show five rows at a time with no pages. With `{warps_from}` at 6, the first row shows the sixth warp, `{warps}` and `{warps_note}` included, and its button runs that warp's command. Step the stepper by the number of rows to move a whole screen at a time (a stepper holds at most 21 positions, so 1 to 26 in steps of 5 works). In a list that is **Repeated a number of times**, the start is the first row's number, and rows past **How many** are hidden; the editor shows `{home_1}`, `{home_2}` and so on where those numbers go. ### Items and inventories The **Items** shelf has an **Item slot**, a **Grid of slots** (up to 13 by 8) and **Your inventory**. Hovering an item shows the game's own tooltip. Set what a grid holds under **What is in it**, and its slot look (inventory, dark well or theme) and **Size** (1×, 2×, 3×) in its panel. **Items you choose.** Pick a slot, then search any Minecraft item or one of your pack's textures, and set its count, name, lore, rarity and enchanted look. **When clicked** works per slot, so each item in a shop can run its own `buy` command. The panel marks items newer than 1.21.6, whose tooltips RP Engine leaves out on an older server so the dialog still opens. **Items from your server's own pack.** A custom item from ItemsAdder, Nexo, Oraxen or a resource pack of your own works too. Pick the item it is made from (often Paper), then under **Your server's own item** give its **Item model** (like `nexo:ruby`) and **Custom model data** (numbers, strings, flags or colours, comma separated; a plugin's number like `1001` goes in **Numbers**). Studio can't see your server's pack, so choose a **Picture in the slot** to draw it; without one the slot shows a question mark. **The player's inventory.** A grid can show the inventory, the hotbar, or the ender chest of whoever opens it, with their real items and tooltips. Your pack's own items show as themselves; items from other plugins show as a question mark with their real tooltip. On Spigot (rather than Paper), tooltips show only name and lore. **Moving items.** Tick **Players can move items** and players can click a stack to pick it up, then click another slot to put it down. Moves work between any movable grids in the dialog, so an ender chest grid over an inventory grid is a working ender chest. The server checks the real slots on every click, so nothing can be duplicated. There is no dragging, shift-click or right-click, and keep such a dialog short enough not to scroll, since it redraws from the top. Plugins can refuse a move with `DialogSlotMoveEvent`. **Other storage.** A grid can also show: - **The item it opened from**, like a backpack. Give an item in RP Engine's content folder (the YAML files in `plugins/RPEngine/content/`, see [RP Engine](/rp-engine)) the `dialog:` action, and its contents are stored on the item itself: ```yaml supply_crate: material: PAPER model: supply_crate actions: right_click: - dialog: studio:supply_crate - cancel: true ``` - **Storage kept on the player** under a name you choose, such as a vault. - **A container another plugin registers** with RP Engine. ### Show when Show when hides a piece from some players: a VIP button only VIPs see, an admin row only staff see. Under **Show when** in any piece's panel, add conditions: a [player setting](#player-settings) or live value compared with something (*is*, *is not*, *is more than* and so on), or a permission the player has or lacks (such as `group.vip` for a LuckPerms group). Choose whether **all** or **any one** must hold. Players they don't hold for see empty space, and the piece's clicks are gone too. **Show something else instead…** puts a stand-in in its place for everyone else, such as a greyed **VIP only** button. The two share a **Show one of** box (up to six pieces), and each player sees the first whose condition holds. **Colour when** keeps the piece for everyone but changes its colours for some players: a talent-tree button that turns green from level 4. The first matching look wins. This is also how a plugin lights up or greys out a button for one player (see [Button looks](#button-looks)). In **Components**, a crossed-out eye marks a piece with conditions, and a palette marks one with looks. ### Sorting a box's pieces A box can show its pieces in an order worked out for each player, a page at a time: a shop whose items are sorted by rarity and then by price, with the ones a player can't buy yet at the end, and a button that switches to sorting by price. Select the box (a grid of item cards, say) and tick **Sort its pieces, a page at a time**. Then: - **Sort name** is what its live values are called. A box named `shop` gives `{shop_page}` (the page shown), `{shop_pages}` (how many there are) and `{shop_count}` (how many pieces this player sees), so a line reading `Page {shop_page} of {shop_pages}` works anywhere in the dialog. - **Per page** is how many pieces it shows at once. Leave it on **All at once** for no pages. - **Page from** is the [player setting](#player-settings) that says which page is shown. Bind a stepper (or buttons) to that setting and it turns the page. A page past the last shows the last. - **Order** lists the ways it can be sorted. Each sorts by one or more properties in turn, lowest or highest first. The first order whose conditions hold is used, and one with no conditions always holds, so an order with a condition on a setting that a segmented control sets lets players choose the sorting in game. Ties keep the order the pieces have in the editor. Each piece then says its own values under **Sort by**, in its panel: `rarity` `0` for a legendary item and `3` for a common one, `price` `450`. A value can be a [live value](#live-values), such as a price your shop plugin gives. **Another value when…** gives a piece another value for some players: `rarity` `-1` when the player lacks `shop.unlock.dragon`, so locked items sort last. The first rule that holds wins. Numbers sort as numbers, and anything else sorts by its letters, after every number. A piece whose [Show when](#show-when) fails is left out and the rest close up, so a page never has a gap in the middle. The editor shows the order a player with the dialog's default settings sees, and selecting a piece shows the page it is on. Things to know: - **Every piece is drawn once for every place it can land in**, so each place is as big as the biggest piece, and a box sorts at most 24 pieces, 12 at a time. A box of 24 pieces shown 12 at a time is 288 copies, which makes a large dialog. The editor warns you when a box gets that big. - A control bound to a setting inside a sorted piece only works in one place. Keep page turners and sort switches outside the box. - A sorted box can't hold another sorted box, a list, or a **Show one of** box directly. - It needs RP Engine. In Dialog Engine its places are empty. ### Icons from your server's pack If your server already has font icons from ItemsAdder, Nexo, Oraxen or a pack of your own, add a **Pack glyph** (Basics) and paste the icon in as a text component (`{"text":"","font":"minecraft:default"}`), MiniMessage (``) or the character itself. Give its **Height** and **Ascent** from the font's JSON, and its **Width** (the picture's width × height ÷ the picture's height); a wrong width shifts whatever follows on the line. Choose a **Picture in the editor** to see it while you lay it out. It moves up and down in 9-pixel steps. A [live value](#live-values) works in a pasted glyph too, so a placeholder can choose the glyph for each player: `{"text":"%card_face%","font":"cards:pixels"}` shows whatever `%card_face%` returns, in that font. The colour codes in the value are kept (`§a`, `§x§f§f§8§8§0§0`, `&a` and `&#ff8800`), so a placeholder that colours its glyphs for each player, such as a face built from one-pixel glyphs, looks the way it does in chat. The glyph's place is as wide as you set, so set **Width** to what the value draws. With RP Engine you can also paste an **RP Engine icon** the way chat writes it: `:mypack:thirst:`, `:thirst:` or ``. RP Engine puts the icon in as the dialog opens and measures it, so its width can't be off. A [live value](#live-values) can pick the icon for each player: `:status:{thirst_state}:` shows whichever icon that value names. Anywhere else, including Dialog Engine, its place is left blank. ## Plugin versions Dialogs open with any version of either plugin that supports them, but these features need at least: | Feature | RP Engine | Dialog Engine | | --- | --- | --- | | Player settings | 0.1.62 | | | Pages | 0.1.66 (instant page turns: 0.1.70) | | | Live words that stay inside their line, live heads | 0.1.69 | | | Inventories and storage, lists, a command of its own | 0.1.74 | | | Bars that follow the player | 0.1.75 | | | Show when, Show one of, Colour when, repeated rows | 0.2.2 | | | Click sounds | 0.2.5 | newer than 0.3.5 | | Seamless after a click | 0.2.6 | 0.4.0 | | RP Engine icons in a Pack glyph | 0.2.10 | not supported | | The Quick Actions key | 0.2.17 | 0.6.0 (straight to a drawn dialog: 0.6.5) | | Colour codes from a placeholder in a Pack glyph | 0.2.34 | 0.6.4 | | Run as console | 0.2.41 | 0.6.6 | | Sorting a box's pieces | 0.2.46 | not supported | | PlaceholderAPI placeholders with arguments | 0.2.48 | 0.6.6 | | Several commands on one button | 0.2.51 | 0.6.7 | | Stay open redrawn after a button's commands | 0.2.57 | | | Scrolling a list (Start at) | 0.2.77 | 0.7.1 | On an older version the feature fails quietly: a bound control shows every state at once, a live bar is empty, a conditioned piece is drawn for everybody, placeholder glyphs come out white, and so on. ## Questions - **`/rp dialog` can't find my dialog.** Press **Sync** again, and check the id with `/rp dialogs`. The server and the player's game both need Minecraft 1.21.6 or newer. - **The screen opens but shows boxes or nothing.** The player doesn't have your resource pack (or has an older copy). Sync again, or check the pack your server sends. - **Can I remove the blur behind a dialog?** No. The game blurs the world behind every menu, and how much is each player's own **Menu Background Blurriness** setting in their video options. Nothing in Studio or the plugins changes it. - **Can a dialog show a 3D Model or a `.bbmodel`?** Not as a model: a dialog is flat pictures and items. Add an **Image** of a render or screenshot of it. - **Can a plugin grey out or select a button when it opens the dialog?** Not directly; see [Button looks](#button-looks). ## Older UI-style dialogs Dialogs made before 30 September 2026 may be in the older UI style: a drawn 256×256 picture with button guides, edited in the GUI editor. They still open, edit and sync as before, but new dialogs aren't made this way. When you open one, the editor asks whether to **Convert** it to the Dialog style or **Keep as it is**. Converting keeps how it looks and what every click does: its picture becomes one image, and each button drawn in it and each clickable area becomes a clickable box in the same place, with the same action and tooltip. Its title, command, inputs and footer buttons carry over; buttons that were drawn in the picture get the game's **Close** in the footer. Its words stay part of the picture, so retype any you want to edit as text pieces. Tick **Keep a backup** to keep a copy of it as it was, named "(backup)". Keep as it is is remembered in that browser. - **Button guides** are the dashed boxes where the game draws each button. Paint inside one to give the button a face; leave it empty for the game's grey button. - **Clickable areas**: pick the **Areas** tool (`A`) and drag a box over any part of the picture to give it an action and a tooltip. - **Size**: the **In game** box under Size says which screens it fits, and **Shrink to fit every screen** makes it fit a 240-pixel-tall screen. - **Nudge**: if the picture sits a few pixels off in game, type an offset in the **Nudge** fields, save and look again. - A UI-style dialog saved before 26 September 2026 only answers clicks on its first line in 1.21.9 and newer. Open it, save, and sync again. --- Source: https://resourcepack.ai/docs/distribution # Distribution Distribution is how you give your pack to **every player on your own server**. You connect your server to a pack once. After that, whenever you press **Publish** in Studio, everyone who joins gets the new version automatically. Studio also shows you who downloaded it. It's the step after testing. **Sync** (see [The plugin](/testing/plugin)) sends a pack to just you while you build it. Distribution is the finished pack your server runs for everybody. You need [RP Engine](/testing/plugin), our free plugin, on the server. ## Setting it up Choose the pack In Studio, open **Distribution** in the sidebar, press **Serve a pack**, and choose the pack your server should hand its players. Connect your server You get an eight-digit code, good for 30 minutes. On your server, as an operator (or anyone with the `rpengine.distribute` permission), run: ``` /rp distribute 12345678 ``` This is called **binding** the server to the pack. The server remembers it, so you do it once. A pack can be bound to up to 10 servers. Publish Press **Publish**, tick the Minecraft versions your players use, and confirm. Each ticked version is built straight away, so nobody waits when they join. Players get the pack the next time they join. No restart is needed. ## Updating the pack Change the pack in Studio as usual, then press **New release** on its Distribution page. It builds your ticked versions again and replaces what players get. There's one live release at a time, and no rollback. Players only ever get what you last published, not what's in the editor, so a half-finished edit never reaches your server. ## Which Minecraft versions to tick Each version you tick is a separate build of the pack. - On an ordinary server, everybody is on the server's version, so tick that. - With [ViaVersion](https://viaversion.com), players can join on other versions. Tick each one you want to support, and see [Players on many versions](#players-on-many-versions) below. - Bedrock players joining through Geyser get a Bedrock version of the pack automatically, if the pack has anything Bedrock can show. See [Bedrock and Geyser](/bedrock). The version breakdown on the Distribution page shows which versions your players are really on, so you can tick any you missed and publish again. Brand-new Minecraft versions A version we haven't added yet shows as unrecognised. Those players start getting the pack once we add it; you don't need to do anything. ## Seeing who got it The Distribution page shows downloads per day for the last 30 days, which versions your players are on, recent joins, and each bound server with the last time it served somebody. **Watch the Declined count.** Players can turn off server resource packs in their server list settings (*Server Resource Packs*) and never see a prompt, and most don't know the setting is there. A high decline count is usually that. Player names and UUIDs come from your server. On an offline-mode server they can be faked, so unique-player counts there are an estimate. ## Pausing and stopping The **Manage** card at the bottom of the Distribution page has two buttons: - **Pause** stops your servers handing out the pack, and keeps everything else. **Resume** starts again with no rebuild. - **Stop distributing** deletes the release, disconnects every server and clears the numbers. The pack itself is kept, and you can start again from **Serve a pack**. Only the pack's owner can do this. To rename a bound server, press the pencil beside its name. To disconnect just one, press the bin beside it. ## On your server When you publish, RP Engine puts the pack in its content folder (the folder of packs it builds and sends to players) as `plugins/RPEngine/content/studio-/`. It's merged with anything else you have there, so players still download one pack. `/rp shaders`, `/rp dialogs` and the rest list what's in it. Each new release replaces that folder within a minute. Make changes in Studio, not in the folder: files you edit there by hand are copied to `plugins/RPEngine/studio-backups/` and then replaced. | Command | What happens | |---|---| | `/rp distribute off` | Disconnects the server and removes the folder | | `/rp distribute off --keep` | Disconnects the server and keeps the folder as your own content, no longer updated | This needs RP Engine 0.2.49 or newer. Older versions send the published pack to each player separately instead of writing the folder. ### Players on many versions The folder holds the build for your server's own version (or the nearest one below it that you published), and that's what every Java player gets. If your players join on many versions through ViaVersion, set `distribution.mode: cdn` in RP Engine's [config](/rp-engine/config#studio): each player is then sent the build for their own version. A player on a version you didn't tick is then sent nothing, and shows up in the version breakdown. **Shader objects or Dialogs not showing?** They need RP Engine 0.2.38 or newer and a release published on or after 29 October 2026. Press **New release** if yours is older. ## Who can publish On your own packs, you. A [collaborator](/collaborators) can see the Distribution numbers if you give them that section, but publishing needs the **Publish to servers** permission, which you grant separately. On a [team](/teams), owners and admins can publish; members can't. ## Limits Every plan can distribute. Starter serves up to 50 different players a month, counted across all the packs you own. Hobby, Creator, Studio and Team are unlimited. Your current usage is on the Distribution page. --- Source: https://resourcepack.ai/docs/emotes # Emotes An Emote is an animation played on a player, in their own skin: a wave, a dance, a handshake, a bench press. You make it once in Studio and every player on your server can play it with `/emote `. A **movement group** goes further and replaces how a player walks, runs and stands while they wear it. ![Players doing emotes: a wave, a cheer, a dance and a point](/images/emotes.webp) Emotes need the [RP Engine](/rp-engine) plugin on your server. A plain resource pack can't play them, and they aren't in a Bedrock `.mcpack`. ## Making one Open a pack, press **Add asset** and pick **Emote**. There are two ways in: - **Generate**: describe the motion and the AI animates it. It costs 25 credits and takes one to five minutes. An emote that uses one of your models (a chair, a sword) can cost more the first time, while that model is rigged. - **Blank**: opens the editor with nothing on the timeline, to key by hand. When generating, describe the movement, not the character: > a little victory dance, fists pumping, then a spin | Setting | What it does | | --- | --- | | **Type** | **Emote** (one animation) or **Group** (see [Movement groups](#movement-groups)) | | **People** | 1 to 5. More than one makes an emote for several players, like a handshake or a hug | | **Playback** | **Play once** holds the last frame at the end. **Loop** repeats until the player moves or runs `/emote stop` | | **Models** | Up to 4 of this pack's models for the emote to use: a chair to sit on, a sword to swing. Mention them in the description | Add models here rather than afterwards if the emote should use them: the AI only animates around what it can see, so a model added later just stands there. A pack holds up to 64 emotes. ## The emote editor The editor works like a model's [Animate mode](/animations): bones down the left, a timeline along the bottom, keyframes for rotation, position and scale. The rig is a standard player with a head, body, arms and legs, plus forearms and shins so elbows and knees can bend. Select **Whole body** to move, turn or scale the entire figure (Ctrl+A). An emote can be up to 30 seconds long. Changes save on their own a moment after you stop editing. The pencil next to the emote's name on the timeline opens its settings: | Setting | What it does | | --- | --- | | **Name** | What players type after `/emote`. The line above it shows the full command | | **Length** | In seconds | | **Playback** | **Once** or **Loop** | | **Wear it while** | Turns the emote into something worn while moving. See below | | **Movement** | **Move the player**: when the emote ends, the player is teleported to where it finished, so a forward flip leaves them a block ahead. Off, they end where they started | The preview uses your linked Minecraft skin. Type any username in **Preview skin** to see the emote on someone else. In game it always plays in the skin of whoever runs it. ### Models The **+** on the shelf above the stage adds one of the pack's models, up to 4. Select it to place it with the gizmo, and choose what it's attached to: **Not attached** leaves it standing where you put it, a bone makes it follow that part (a sword in the right hand), and **Whole body** makes it follow the figure. Its position can be keyframed like a bone. If the model has its own animation, that plays in time with the emote. ### Other players The other **+** on the shelf adds another person, for up to 5 in total. The first is always **Lead**, whoever runs the command. Each added person has a name, a place relative to the lead and a direction to face. In game they're moved into position when the emote starts and put back when it ends, and the command takes their names in order: ``` /emote handshake Steve ``` Every invited player is asked first and can refuse. ### Render **Render** dresses the viewport for showing off (a backdrop, a floor, a slow turn) and exports the emote as a video, in MP4 or WebM depending on your browser. ## Movement groups A group is a set of emotes a player **wears** rather than plays once: a heavy armour stomp, a strut, a zombie shuffle. It holds one emote per movement state: | State | When it plays | | --- | --- | | **Standing still** | Idle | | **Walking** | Moving at normal pace | | **Sprinting** | Running | | **Crouching in place** | Sneaking without moving | | **Crouching while moving** | Sneak-walking | | **Jumping** | Off the ground, jumping or falling | A state left empty uses the player's normal animation. Many sets look best with only a walk and an idle. To make one, press **Add asset**, pick **Emote**, then **Group** (groups are made blank, since they're built from emotes). Name the group, then for each state choose **Use an existing emote**, **Generate one** or **Draw a new one**. A pack holds up to 16 groups. Deleting a group keeps its emotes. A player puts one on with `/emote ` and takes it off with `/emote stop`. While it's on they play normally: same game mode, free to walk, jump and fight. **Draw walk cycles at Minecraft's normal pace.** In game a walk, sprint or crouch-walk cycle is driven by how far the player moves, not by time, so the feet don't slide on ice, soul sand or with a speed potion. Draw each one for the normal speed below and it plays as drawn: | State | Draw it for | | --- | --- | | Walking | 4.317 blocks per second | | Sprinting | 5.612 blocks per second | | Crouching while moving | 1.295 blocks per second | **You won't see it on yourself.** Everyone else sees your rig; your own view stays vanilla, so your arm, held item and hotbar are your own. To check how it looks while testing, use: ``` /emote --showYourself ``` The rig visibly lags a step behind you that way, so don't leave it on for real play. A single emote can be worn too: tick states under **Wear it while** in its settings and it plays in those states. That isn't available for an emote with other players in it, since they're held in place around the lead. ## Getting it in game Install RP Engine On your server. See [Installing RP Engine](/rp-engine/install). Sync Press **Sync** in the pack or the emote editor, and run the `/rp sync ` it shows in game. That sends the pack, emotes included, to you on that server. For every player, serve the pack with [Distribution](/distribution). Play it `/emote `, or `/emote` and Tab to list them. Each emote's card on the pack page has a button that copies its command. A player needs a rig (a copy of the emote built from their own skin) in the pack before they can emote. RP Engine makes these automatically. If someone who joined after the last sync can't emote, sync again. Hand-written emote files, permissions, what stops an emote and the server's settings are all on [Emotes in RP Engine](/rp-engine/emotes). --- Source: https://resourcepack.ai/docs/exporting # Exporting Exporting turns your pack into a file you can install, upload to a server, or hand to a friend. You don't need to export to test a pack: **Sync** sends it straight to your game (see the [Quickstart](/quickstart)). ## Which export do I need? There are several **export targets**, one for each place a pack can go. Pick by where it's going: | You want to | Choose | | --- | --- | | Use it in your own Java game, or send it to every player from `server.properties` | **Minecraft: Java Edition** | | Use it in a Bedrock world or Realm | **Minecraft: Bedrock Edition** | | Give it to Bedrock players on a Java server running Geyser (without RP Engine) | **Bedrock players on a Java server** | | Use your Dialogs without RP Engine | **Dialogs (minecraft:dialog)** | | Add it to a server running ItemsAdder, Nexo, Oraxen, CraftEngine or Model Engine | That plugin's name, on the **Plugin Support** tab | Running [RP Engine](/testing/plugin), our plugin? You don't need any of these for your server: [Distribution](/distribution) sends the pack to your players for you. ## Exporting a pack Open the pack and press **Export** (or right-click its card and choose **Export**), then pick a target. The file is built on the spot from what's in the pack right now, and downloads. ## All the targets The Export dialog has two tabs. **Default Pack** is for files you install or serve yourself, with no other plugins involved: | Export | File | Use it for | | --- | --- | --- | | **Minecraft: Java Edition** | `.zip` | The ordinary resource pack. Goes in `resourcepacks`, or on a server | | **Minecraft: Bedrock Edition** | `.mcpack` | The Bedrock version, converted. Open it on any Bedrock device to import it | | **Bedrock players on a Java server** | `.zip` | The `.mcpack` plus the item list Geyser needs, for a server running Geyser without RP Engine | | **Dialogs (minecraft:dialog)** | `.zip` | Your Dialogs as a vanilla datapack | **Plugin Support** is for servers running another plugin that makes custom items and builds its own resource pack. What you get isn't a resource pack: it's your content in that plugin's format, and the plugin builds the pack from it. | Export | File | Use it for | | --- | --- | --- | | **Model Engine** | `.zip` of `.bbmodel` | Animated models on a server running [Model Engine](https://git.mythiccraft.io/mythiccraft/model-engine-4) or [BetterModel](https://modrinth.com/plugin/bettermodel) | | **ItemsAdder** | `contents` folder | A server running [ItemsAdder](https://wiki.itemsadder.com/) | | **Nexo** | `.zip` | A server running [Nexo](https://docs.nexomc.com/) | | **Oraxen** | `.zip` | A server running [Oraxen](https://docs.oraxen.com/) | | **CraftEngine** | `.zip` | A server running [CraftEngine](https://modrinth.com/plugin/craftengine) | Every plugin export includes a `README.txt` listing each item id, anything that couldn't be carried over and why, and any model left out because it hadn't finished generating. Animations need RP Engine In the Java `.zip`, a model shows but stands still: vanilla Minecraft can't play model animations. Playing them needs [RP Engine](/testing/plugin) on the server. Bedrock can play animations itself, so the `.mcpack` keeps them. ## Installing the Java pack Put the `.zip` in your `resourcepacks` folder and turn it on in **Options › Resource Packs**: ```bash # Windows %APPDATA%\.minecraft\resourcepacks # macOS ~/Library/Application Support/minecraft/resourcepacks # Linux ~/.minecraft/resourcepacks ``` To send it to everyone on a server, upload the file somewhere players can download it and set `resource-pack` (its link) and `resource-pack-sha1` in `server.properties`. That needs nothing of ours installed, and the file keeps working if you never open Studio again. ## Bedrock Bedrock uses a different pack format, so the `.mcpack` is a conversion. Open it on any Bedrock device and it imports itself; then turn it on under the world's **Resource Packs**. In a world on its own, a `.mcpack` shows your Block and Item reskins, Sounds, Armor and Icons. Custom items, models and 3D Armor need a server: a Java server running Geyser (with RP Engine for all of it, or with the **Bedrock players on a Java server** export for custom items). GUI screens, the HUD, Shaders, Dialogs, Emotes and Vehicles don't exist on Bedrock and are left out. [Bedrock and Geyser](/bedrock) has the full list and the steps for each route. ## Dialogs as a datapack A [Dialog](/dialogs) is a menu screen with real buttons. Minecraft keeps Dialogs in a datapack (a world's data folder), not a resource pack, so they have an export of their own: ``` pack.mcmeta data/studio/dialog/.json each dialog data/studio/dialog/..json each page after the first ``` Put the zip in your world's `datapacks` folder and **restart the server** (`/reload` isn't enough, because dialogs are loaded with the world). Then open one with `/dialog show @s studio:`. Dialogs need Minecraft 1.21.6 or newer. The pictures inside a Dialog are in the Java pack, so players also need the Java pack exported at the same time, or the screen is blank. If you keep a resource pack of your own, the dialog editor's **JSON › minecraft:dialog › Resource pack (.zip)** downloads just that dialog's pictures and fonts; see [Dialogs › Without RP Engine](/dialogs#without-rp-engine). On a server without RP Engine, the parts that change per player don't work: `{placeholders}` show as typed, settings switches stay on their default, live heads, inventory slots and bars are empty, and `/rp` clicks do nothing. The editor's **JSON › minecraft:dialog** view lists which of those a dialog uses. ## Model Engine and BetterModel Model Engine and BetterModel are server plugins for animated models. This export gives them your 3D Models as Blockbench files, one `.bbmodel` per model, with every texture it uses packed inside. ``` blueprints/ your_model.bbmodel README.txt ``` **Model Engine:** copy the files into `plugins/ModelEngine/blueprints/`, run `/meg reload`, then `/meg summon ` to look at one. Command names vary between Model Engine releases, so run `/meg` on its own for your version's list. **BetterModel:** reads the same files. Copy them into `plugins/BetterModel/models/` and reload BetterModel. Checkerboard models mean the pack isn't being sent Model Engine writes its textures to `plugins/ModelEngine/resource pack/` and stops there. Players who aren't sent that pack see the model as a black-and-magenta checkerboard. If ItemsAdder runs on the same server, add this to ItemsAdder's `config.yml`, then `/meg reload`, `/iazip` and rejoin: ```yaml merge_other_plugins_resourcepacks_folders: - "ModelEngine/resource pack" ``` Otherwise, merge that folder into whatever pack your server already sends. What to expect: - **Models only.** Block textures, item sprites, GUIs and icons belong in the Java zip or one of the other plugin exports. - **Bones keep their tree.** A child bone sits inside its parent, so it moves with it. A model with no bones gets one `root` bone. - **A `hitbox` bone is added**, sized to the model. Redraw it in Blockbench for a different collision box. Mount and seat bones (`mount`, `p_*`) are not written. - **Animations don't start on their own**, and Model Engine has no command to play one. It plays a few names automatically as entity states (`idle`, `walk`, `jump`, `death`, `spawn`), so an animation named **Idle** loops on any summoned model. Names are snake_cased, so "Idle Wave" becomes `idle_wave` and won't auto-play. Anything else needs MythicMobs, Model Engine's API or a plugin such as [MEGAnim](https://hangar.papermc.io/Nogard/MEGAnim). - **Triggers don't come across.** On loop, on click and on range are RP Engine ideas. The `README.txt` lists each model's animation names as exported. If a rig looks wrong in game, open its `.bbmodel` in Blockbench: what you see there is what Model Engine renders. ## ItemsAdder ItemsAdder is a server plugin for custom items, blocks and furniture. It builds and sends its own resource pack, so this export is your pack as ready-made ItemsAdder content, with the config written for you. ``` contents// configs/items.yml furniture, items and custom blocks configs/font_images.yml icons and GUI overlays resourcepack/assets/ / your models, textures, icons and sounds minecraft/ the vanilla files your pack replaces datapacks/_dialogs/ your dialogs, if any RPEngine/content// the same dialogs, for RP Engine README.txt ``` Merge the zip into `plugins/ItemsAdder/`. It already contains `contents/`, so unzipping it *inside* `contents/` gives you `contents/contents/` and ItemsAdder finds nothing. Then: ``` /iazip rebuild the pack /iaget : give yourself one /iagive : give someone else one ``` Ids are lowercased with other characters turned into underscores: a model called "Floating Sword" in a pack called "My Pack" is `my_pack:floating_sword`. | In your pack | Becomes | | --- | --- | | 3D model | Furniture: right-click the floor with it to place it, hit it to break it. Its hitbox is barrier blocks measured from the model | | 3D item | An item with a custom model, held rather than placed (on `PAPER`; change `material` in `items.yml` if you like) | | Custom block | An ItemsAdder note-block block: hardness 2, stone sounds, drops itself, faces whoever placed it if directional | | Vehicle | Furniture with one seat you can sit in, not drive | | 2D custom item | An item built from its sprite | | Icon | A `font_image`, with a character ItemsAdder chooses. Use its ItemsAdder placeholder | | Sound | `:`, playable with `/iaplaysound`. A sound replacing a vanilla one still replaces it | | GUI replacing a vanilla screen | A vanilla file replacement | | GUI overlay | A `font_image`, with its ready-made title string (such as `:offset_-176::gui_bank_vault:`) in the `README.txt` | | Block or item reskin | A vanilla file replacement | | Dialog | A datapack folder and an RP Engine folder | The export never writes the files ItemsAdder owns (`paper.json`, blockstates, the default font) and sets no `CustomModelData`, so it can't clash with content you already have. Things to know: - **Vanilla replacements apply to every player.** Delete any you don't want from `resourcepack/assets/minecraft/` and run `/iazip` again. - **Re-export after editing a GUI.** The overlay's title string is measured from its art, so an old title won't line up with new art. - **Animated models arrive static.** ItemsAdder doesn't play keyframes. - **Sounds replacing vanilla ones** go in a `sounds.json` that ItemsAdder merges with its own. ItemsAdder releases older than December 2023 don't merge it; on those, delete that file or ItemsAdder's custom block sounds go quiet. - **Dialogs need Minecraft 1.21.6+**, and `/iazip` before anybody opens one. With [RP Engine](/rp-engine) 0.2.1 or newer, merge the zip's `RPEngine/` folder into `plugins/`, run `/rp reload`, and open one with `/rp dialog : `; RP Engine fills in placeholders, settings, bars and inventories. Without it, move the datapack folder into your world's `datapacks/`, restart, and use `/dialog show studio:`; nothing per-player is filled in. A dialog synced from the editor won't work on an ItemsAdder server, because its characters clash with ItemsAdder's. ## Nexo and Oraxen Nexo and Oraxen also build the pack themselves. These two exports are the same content written in each plugin's format. ``` Nexo/ Oraxen/ items//items.yml items//items.yml glyphs//glyphs.yml glyphs//glyphs.yml pack/external_packs// pack/uploads// datapacks/_dialogs/ datapacks/_dialogs/ ``` Unzip it straight into `plugins/`, then: ``` /nexo reload all /oraxen reload all /nexo give /oraxen give ``` | In your pack | Becomes | | --- | --- | | 3D model | Furniture: hold it, or right-click a block to place it, with a hitbox measured from the model | | Vehicle | Furniture with the vehicle's seats, to sit in | | Custom block | The plugin's own note-block block | | 2D custom item, 3D item | An item, keeping its name and base item | | Vanilla item in 3D | The vanilla item, reskinned | | Icon | A glyph: `_>` in the plugin's text, `:icon:` in chat. It keeps its character | | GUI overlay | A glyph, with its title string (such as ``) in the `README.txt` | | Pause-menu buttons | The redrawn buttons | | Sounds | Merged in under your event names | | Block, Item, Armor or GUI reskin | A vanilla file replacement | | Dialog | A datapack folder | Both plugins merge fonts, `sounds.json` and language files, so the export sits beside what your server already has. It sets no `CustomModelData` and picks no block states; the plugin chooses those and writes them back into `items.yml`. Dialogs go in your world's `datapacks/` folder, then restart and use `/dialog show studio:` (Minecraft 1.21.6+). Vanilla replacements apply to every player: delete any you don't want from the pack folder's `assets/minecraft/` and reload. Some things only RP Engine can draw while the game runs, so they can't be expressed in these plugins' config. The `README.txt` names each one your pack has: shader objects, 3D Armor, model animations (models place as still furniture), driving (vehicles are furniture you sit in) and dialog settings switches (they open, but only RP Engine remembers a choice). ## CraftEngine CraftEngine builds its pack from one folder per pack. This export is that folder. ``` CraftEngine/resources// pack.yml configuration/items.yml items, furniture and blocks configuration/images.yml icons, GUI overlays and chat emoji configuration/categories.yml a category in the item browser resourcepack/ models, textures, sounds, replacements datapacks/_dialogs/ ``` Start CraftEngine once before you unzip CraftEngine only installs its own default packs into an empty `resources/` folder, and custom blocks need them. Unzip into a server that has already started with CraftEngine. Unzip into `plugins/`, then: ``` /ce reload all rebuild and resend the pack /ce item get : give yourself one /ce the item browser, with your pack as a category ``` It maps the same way as Nexo and Oraxen, with these differences: - **Custom blocks are real CraftEngine blocks**, with their own hardness and drop. CraftEngine picks the block state. - **Furniture** can be turned by sneak-clicking it with an empty hand. - **Icons** are images (`:>`) and also chat emoji typed as `:icon:` in chat, books, signs and anvils. GUI title strings use ``. - **Characters are pinned.** `images.yml` holds one invisible image, `:reserved`, that keeps the characters your pack uses for spacing and dialog art free. Leave it in, or another pack's emoji can land on one of them. - It doesn't use CraftEngine's bundled templates, so it still loads if you've removed `default_templates`. Dialogs and the RP Engine-only features work as described for [Nexo and Oraxen](#nexo-and-oraxen). --- Source: https://resourcepack.ai/docs/generating # Generating with AI Generating means describing something in words and having the AI make a first version of it: a Block texture, a 3D Model, a Sound. You then finish it in the editor. Each generation costs **AI Credits**, the app's currency, and the price is shown before you start. ## Generating something Open Add asset On your pack's page, press **Add asset**. Pick what you're making Choose a tab along the top (Model, Block, Item and so on), then **Generate**. Fill in the form Write your prompt. Depending on the type you also pick which vanilla block or item it replaces, a size for pixel art, or a sound event name. Press Generate The cost is on the button. Most things take a minute or two, a 3D Model a few minutes, and you can leave the page while it works. The new asset appears in the pack when it's ready. If you can't think how to phrase it, press **Write a prompt for me**, say what you want in a few words, and it fills in the prompt box. That's free. Making a lot at once, or a whole pack? Press **Chat** instead and describe it: you get a list of everything to make, with prices, and generate it all with one button. See [Chat](/chat). ## What each type can start from **Generate** is the AI. **Blank** opens the editor empty. **Upload** uses a file you already have. | Type | Generate | Blank | Upload | | --- | --- | --- | --- | | **Model** | ✓ | ✓ | `.json` `.bbmodel` | | **Block** | ✓ | ✓ | `.png` `.jpg` `.webp` | | **Item** (2D or 3D) | ✓ | ✓ | `.png` for 2D, `.json` or `.bbmodel` for 3D | | **Armor** (2D or 3D) | ✓ | ✓ | `.png`, or `.bbmodel` for 3D | | **GUI** | ✓ | ✓ | `.png` (256×256 sheet) | | **Dialog** | ✓ | ✓ | ✕ | | **HUD** | ✓ | ✓ | `.png` sheet | | **Icon** | ✓ | ✓ | `.png` `.jpg` `.webp` | | **Rank Tag** (on the Icon tab) | ✓ | ✓ | ✕ | | **Sound** | ✓ | ✓ | `.ogg` `.mp3` `.wav` | | **Emote** | ✓ | ✓ | ✕ | | **Shader** (2D or 3D) | ✓ | ✓ | ✕ | | **Text Effect** | ✓ | ✓ | ✕ | | **VFX** | ✓ | ✓ | ✕ | Pixel art comes in fixed sizes: a generated Block is 16 pixels across, a 2D Item 16, 32, 64 or 128, and an Icon 8, 16, 32, 64 or 128 pixels tall. Blocks, 2D Items and Icons are each drawn 4 times, and you get the best one (see below). An emote **Group** (a set of Emotes a player wears while moving) is made from Emotes you already have, so it's started blank. Vehicles and Mobs start as a 3D Model: see [Vehicles](/vehicles) and [Mobs](/mobs). Skins are made from their own page: see [Skins](/skins). ## What it costs Every generation spends AI Credits. How many you get depends on your plan: | Plan | AI Credits | | --- | --- | | Starter (free) | 50 every 30 days, from the day you sign up. Each 30 days' credits run out when the next 50 arrive | | Hobby | 200 a month | | Creator | 500 a month | | Studio | 1,500 a month | | [Team](/teams) | None of its own: members top it up | Credits from a paid plan, and credits you buy as a top-up, never expire. Your balance is on your [account page](https://studio.resourcepack.ai/account). When it is too low for what you picked, **Generate** opens **Upgrade** instead. If credits you expected aren't there, contact support (see [Getting help](/#getting-help)): this page and the Ask AI assistant can't see your account. The exact estimate is always shown next to the **Generate** button before you press it, so this table is a guide rather than a price list. | Type | Credits, about | Time, about | | --- | --- | --- | | Model, or a 3D Item | 75 | 3–6 min | | Mob, generated and animated | 113 | 7–18 min | | Block | 10 (fixed) | under 2 min | | Item (2D) | 5 | under 30 sec | | Icon | 5 | under 30 sec | | Rank Tag | 5 (fixed) | under a minute | | Sound | 7 per take | under 10 sec | | Armor | 45 | 2–5 min | | Armor (3D) | 150 | 15–25 min | | GUI | 40 | 2–12 min | | HUD | 2 per part you tick | 1–4 min | | Dialog | 30, plus 5 per extra page | 1–3 min | | Emote | 25 | 1–5 min | | Shader (2D) | 10 | under a minute | | Shader (3D) | 30 | 4–6 min | | Text Effect | 20 | 2–5 min | | VFX | 30 | 1–3 min | | Skin | 45 | 2–5 min | | Edit with AI, on a model | 10 | 1–5 min | | Animate with AI, on a model | 15 | 1–5 min | Except where it says fixed, you're charged for what the run actually used, so it can come in a little under or over the estimate. **A generation that fails is refunded automatically.** ### Free credits from Discord - **Join**: connect Discord on your [account page](https://studio.resourcepack.ai/account) and join [our Discord server](https://resourcepack.ai/discord) for 50 credits, once per account and once per Discord account. - **Boost**: boosting the server earns 50 the moment you boost, then 50 more for every 30 days you keep boosting. The first 50 comes once per Discord account, and only unbroken boosting counts, so stopping and boosting again starts the count from zero. If Discord isn't connected yet, the credits arrive the moment you connect it. ## Giving it a picture to work from Every type except Sounds, Emotes and Rank Tags can take a **reference image** beside the prompt, and the AI works from it as well as from your words. A model built from a reference picks up its shape and colours, which is often the quickest way to get "like this, but Minecraft". Add one with: - **Upload**: a picture from your computer (or drop one on the form). - **From pack**: something already in the pack. - **From Sketchfab**: paste a Sketchfab model's link and it's used as inspiration. Models whose licence doesn't allow commercial use, or whose author opted out of AI, can't be used. ## Writing a prompt Be specific about **material, colour and structure**. Don't describe pixels: the AI can't count them, and asking it to costs you the parts it's good at. | Good | Bad | Why | | --- | --- | --- | | *weathered copper roof tiles, blue-green patina, strong diagonal grain* | *a nice block, 4px border, dark at the bottom, make it pop* | Material and wear beat pixel instructions | | *oak market stall, striped red canopy, crate of apples on the counter* | *a detailed medieval shop with lots of decorations* | Named parts give the AI something to build | | *golden key, ornate bow, three teeth* | *cool key* | The parts you name are the parts you get | | *heavy iron door slamming, echo in a stone hall* | *scary sound* | Say what makes the noise and where | | *a red potion bottle, thick dark outline* | *tiny detailed potion icon with sparkles and reflections* | At icon sizes, detail turns to noise | Things worth naming: - **The material.** "Oxidised copper" gets further than "green metal". - **The wear.** New, weathered, cracked, mossy. This is most of what makes a texture look like it belongs in Minecraft. - **The structure.** Planks, tiles, bricks, panels. Give the eye a repeating unit. - **What it sits next to.** "Reads next to deepslate" is a real instruction and the AI will use it. If your pack has a **Style Guide**, the Generate form offers to use it, which keeps colours and style consistent across everything you make. ## If it isn't quite right Most generated assets, Skins included, have **Edit with AI** on their page: describe the change ("same block, fewer colours, calmer surface") and it edits what's there rather than starting again, so you keep the colours and shape you liked. On a model it looks at the model's parts first and changes only what you asked for. **Regenerate** runs the original prompt again; the old version stays in the asset's AI history. A Block, 2D Item or Icon you generate from a description is drawn 4 times, and Studio picks the best one. On Creator, Studio or a Team the **Versions** card on its page shows all 4, and clicking another uses it instead, for free. That is often quicker than another prompt. Edit with AI costs credits like any generation, and on a texture it can change pixels you didn't mention. If you've painted something by hand, duplicate it first. Once the shape and colours are right, switch to the editor. Fixing eight pixels by hand takes fifteen seconds and gets you exactly what you meant; three more prompts take minutes and give you something slightly different each time. ## Getting told when it's done You don't have to watch a model build. Turn on a notification and close the tab: anything that runs for more than two minutes sends one when it finishes or fails, with a link back to it. The settings are on your [account page](https://studio.resourcepack.ai/account), under **Notifications**. Each channel is separate: | Channel | Needs | | --- | --- | | **Email** | A verified email address on your account | | **Discord** | Discord connected to your account, and you in [our Discord server](https://resourcepack.ai/discord) | | **In game** | Your Minecraft account linked; the message arrives on | Discord messages need both A Discord bot can only message people it shares a server with. Connect Discord and join ours, or no message arrives. If they still don't, check that direct messages from server members are allowed in your Discord privacy settings. In-game messages aren't saved for later. If you're offline when it finishes, you won't get one, so turn on email too if you want a message that waits. --- Source: https://resourcepack.ai/docs/guis # GUIs A GUI asset gives one of Minecraft's **screens** a new look: a chest window turned into a shop menu, a furnace, an anvil, the player's own inventory, the Escape menu. You can have the AI design the whole screen, lay it out yourself with buttons, text and icons, or paint over the vanilla art by hand. ![Two GUIs made in Studio: a painted market menu and a blocky shop menu](/images/guis.webp) A GUI changes the look, not the layout A resource pack can't move a slot, add one, resize the window or change what a click does. That's server code. Design around the slots the screen already has: the buttons you draw are pictures over slots, and a server plugin decides what clicking each slot does. Two other kinds of screen have their own pages or sections: - **Menus with real buttons and text fields** (a welcome screen, a settings menu) are [Dialogs](/dialogs). - **Screens you write in HTML and CSS**, with a mouse pointer and any layout you like, are [Custom GUIs](#custom-guis), shown by the MC GUI plugin. ## Which screens you can change | Kind | Screens | Who sees it | | --- | --- | --- | | **Overlay** | Chests (1 to 6 rows), Shulker Box, Dispenser / Dropper, Hopper, Crafting Table, Furnace, Blast Furnace, Smoker, Smithing Table, Stonecutter, Grindstone, Loom, Cartography Table, Enchanting Table, Anvil, Brewing Stand | Only screens a plugin opens with this GUI's title. Ordinary chests stay ordinary | | **Player Inventory** | The E screen | Every player with the pack, always | | **Escape Menu** | The pause screen's buttons and background | Every player with the pack, always | An **overlay** is the usual choice for a server menu. Your art is drawn on top of the screen whenever a plugin opens it with the GUI's special title, which Studio gives you. Because your art can be bigger than the window, you can draw outside it: a banner, a frame, hanging chains. The dashed rectangle in the editor is where vanilla's window sits. (The beacon isn't offered: it has no title to draw on.) The **Player Inventory** replaces vanilla's inventory picture, so a pack holds one, and anything outside the 176×166 window isn't drawn. The **Escape Menu** themes the shared button face (with its hover and disabled states), the background, and each button's label, generated from one description of the material. A pack holds one. Because the button face is shared, the title screen, options screens and world list get the same look. Each button's art replaces its words, and the pause screen's buttons no longer light up under the cursor. It opens in the pixel editor, with a guide box round each sprite. ## Making one Open a pack, press **Add asset** and pick **GUI**, with **GUI** chosen at the top (the other choice, **Custom GUI**, is [below](#custom-guis)). **Generate** takes a description and a **Layout**: - **Planned for you**: describe the whole screen, "an underwater pirate shop", and the AI picks the size, title, sections, buttons and layout. Your words decide the look. Name no style and it keeps Minecraft's own grey window. Name a theme or colours ("a witch shop", "dark blue and silver", "clean modern") and it repaints the whole screen to match. Ask for drawn art ("painted", "made of wood", "illustrated cards") and it draws pictures and item sprites too. Everything lands as separate layers you can keep editing. - **Design it yourself**: pick the **Screen to reskin** and place the buttons and drawings yourself. For the Player Inventory you choose whether to draw the slot cells and colour them from your panel; vanilla owns the rest of the layout. **Blank** starts from the real vanilla art for the screen, centred on the sheet. **Upload** takes a 256×256 sheet. On a chest GUI's page, **Edit with AI** rebuilds the screen with one change made ("make the frame gold", "add a sell button"). It costs about the same as generating one, and a failed edit leaves the screen as it was. ## The editor The GUI editor shows the vanilla window frame and a guide box on every slot (and on the player's inventory and hotbar below most screens), so you can line a panel up with the grid. Add pieces from its add menu: **Blank**, **Button**, **Text**, **Formatted text**, **Icon**, **QR code**, **Scroll bar**, **Tabs**, **Upload image**, **AI image**, **Title plate**, **AI title plate**, **Background** and **Player head**. A player head shows the viewer's own face and needs RP Engine on the server. Everything is a layer you can move and edit. `Ctrl+C` copies the selected piece and `Ctrl+V` pastes it, into this GUI or another one in any tab. Pasting pixels copied from a texture, or an image copied outside Studio, adds it as an image. ### Your own fonts Words can be set in a font of your own. Under **Font** in a piece's panel (a text, title plate, button, tab or formatted text), choose **Upload a font (.ttf)**. The font is kept with the pack, so every GUI, HUD, dialog and rank tag in it can use it. A **Game** style button can use one too, in place of Minecraft's letters. The **Text** tool has the same choice: the editor's own fonts, the pack's, an upload and a size. So does the Text tool in the HUD editor. The words are drawn into the screen as pixels, so nothing extra ships and no player needs the font. Fonts work the same way as in dialogs: see [Your own fonts](/dialogs#your-own-fonts) for sizes, file types and other alphabets. In short: - A font with no English letters (Thai, say) uploads and draws, with any missing English letters and digits taken from Minecraft's font. The panel lists which characters came from Minecraft's font. - Words in another alphabet (Thai, Chinese, Japanese, Russian) are set in the first font of the pack that has their letters, even if you haven't picked it for that piece. - The editor's own fonts (Classic, Small Caps, Tiny) have English letters only. An accented letter is drawn without its accent, and a symbol they lack is drawn as Minecraft draws it. - Right-to-left and joined scripts (Arabic, Hindi) don't draw correctly. ## Seeing it in game **An overlay** needs something to open it. With [RP Engine](/rp-engine), our free server plugin, the GUI's page has an **Open in-game** button, and the command it runs: ``` /rp screen studio: @p ``` It needs the `rpengine.screen` permission (op by default); the button works without it. The screen is real, so you see your art against real slots and items. First [Sync](/testing/plugin) the pack, which sends it to you in game. **The Player Inventory and Escape Menu** need no command: Sync the pack and press E or Esc. ### Opening it from your own plugin Without RP Engine, your plugin opens the inventory with the GUI's title, shown on its page, in white. The title looks blank but holds the characters that draw your art: ```java // Copy the title from the GUI's page in Studio. Inventory inv = Bukkit.createInventory(null, 54, Component.text("").color(NamedTextColor.WHITE)); player.openInventory(inv); ``` The picture is drawn in the title's colour, so a coloured title tints the whole screen. Moving a GUI to another pack changes its title The title's characters are given out per pack, so a GUI copied into another pack gets new ones. Copy the title from its page again. A Player Inventory or Escape Menu won't copy into a pack that already has one. ## Custom GUIs A **Custom GUI** is a set of web pages, written in HTML and CSS, that the [MC GUI](/mcgui) server plugin shows in game: full screen with a mouse pointer, or on a wall of maps players walk up to and click. It isn't tied to a vanilla screen, so the layout is yours: a server menu, a shop with tabs, a leaderboard, a rules board. It's the same editor as [mcgui.dev](https://mcgui.dev), kept in your pack. | | Chest GUI | Custom GUI | | --- | --- | --- | | Layout | Vanilla's window and slots | Anything HTML and CSS can lay out | | Holds real items | Yes | No | | Needs | Your pack, plus a plugin to open it | The [MC GUI](/mcgui) plugin (it makes its own resource pack) | | Gets to the server | Sync or export | **Send to server**, then `/mcgui import` | ### Making one Add it Press **Add asset**, pick **GUI**, and choose **Custom GUI** at the top. **Generate** asks you to describe it ("a server menu with my level, who's online and buttons for Kits, Rewards and Warps"); the editor opens and writes the first page as you watch. **Blank** starts from an empty page or a template (Server menu, Shop, Server selector, Leaderboard, Rules or Style guide). Change it The editor shows the page as a player will see it, and you can click through it like the game. Type a change into the AI bar under the preview ("add a Back button", "make it a dark theme"), or switch views along the top: **Map** shows every page and how buttons link them, **Page** lets you click any part of a page to make it a link, and **Code** is the HTML and CSS itself. Changes save as you go. Send it to your server Press **Send to server**. You get a command like `/mcgui import abcd1234`. Run it in game or in the server console on a server with MC GUI installed, then `/mcgui open ` shows it. Sending the same Custom GUI again replaces what the last import put there. Each AI request (a new page or a change) costs **10 AI Credits**. Editing by hand is free. Custom GUIs are listed on the pack's **GUIs** tab beside your other screens. They aren't part of an exported resource pack or a Sync: MC GUI builds the pack its pages need on the server. To put the files on a server by hand, **Export** downloads them as a `.zip` for `plugins/MCGUI/pages/`. See [MC GUI](/mcgui) for installing the plugin, what a page can use, and its commands. ## What's in the exported pack An overlay is a PNG under `assets/minecraft/textures/font/` plus an entry in the pack's font file. Nothing under `textures/gui/` changes, which is why ordinary screens stay ordinary. The Player Inventory is `assets/minecraft/textures/gui/container/inventory.png`, and the Escape Menu is vanilla's button sprites plus label overrides. Both work as soon as the pack is applied. ## On Bedrock GUIs are Java-only. Bedrock draws its screens differently. The rest of your pack converts as normal. --- Source: https://resourcepack.ai/docs/hud # HUD The HUD is everything Minecraft draws over the world when no screen is open: hearts, the hunger row, armor, air bubbles, the hotbar, the experience bar, the boss bar and the crosshair. A HUD asset gives all of it one theme from one description, and you can finish it by hand afterwards. ![A HUD made in Studio: hotbar, hearts, hunger, armor, experience bar and crosshair](/images/hud.webp) Reskin, not add A HUD asset changes what vanilla's pieces look like. It can't add new ones, such as a thirst meter, an ammo counter or a quest tracker. For those, build a [shader object](/shaders): your own HUD element placed anywhere on screen, with live values like `{health}`. A pack holds one HUD, because each piece replaces a vanilla file. ## Making one Open a pack, press **Add asset** and pick **HUD**. Describe the theme, for example "rusted iron and dried blood" or "frosty winter". Under **Parts to redraw**, every part starts ticked. Untick the ones you want left vanilla; the price follows what's ticked, because you're charged per part. Naming a part in your description ("make the hunger bar look like roasted meat") ticks it back on, and a line under the list says so. It matches words like hearts, hunger or food, armor, air or bubbles, xp, crosshair, hotbar and boss bar. | Part | What one drawing becomes | | --- | --- | | **Hearts** | Every heart: full, half and empty, in the poisoned, withered, frozen, absorbing and hardcore moods, with and without the damage flash | | **Hunger** | The food row, including the version drawn while you have Hunger | | **Armor** | The armor row | | **Air** | The breath bubbles | | **Hotbar** | The tray, its selection box, the offhand slot and the attack indicator | | **Experience bar** | The groove and the fill | | **Boss bar** | All seven colours, groove and fill, plus the notched dividers | | **Crosshair** | Picked from a list, not generated (free) | The AI picks a style for the hotbar, the selection box and the bars, a palette, and draws the four icons (heart, food, armor, air). Every state of an icon (half, empty, poisoned, frozen, hardcore and so on) is worked out from that one drawing. Name a thing and it draws that thing: "banana hunger" puts a banana where the drumstick goes. Attach a reference image to steer the look. Once it's made, **Edit with AI** on the HUD's page changes it from a sentence ("make the hearts blue", "a thinner hotbar") and keeps everything you didn't ask about. ### Crosshair styles A pack can't use vanilla's colour-inverting crosshair, so a replacement is drawn as a light shape with a dark outline to stay visible everywhere: **Cross**, **Plus**, **Dot**, **Brackets**, **Circle**, **Diamond** or **Chevron**, in your HUD's palette. ### Starting from vanilla The **Blank** door makes a HUD from vanilla's own art for free, no prompt needed, and opens it in the HUD editor: the quick way to "vanilla, but golden hearts". ## Seeing it in game On a server running [RP Engine](/testing/plugin), our free plugin, press **Sync** to send the pack to yourself in game, and look at your screen. Without a plugin, [export](/exporting) the pack and apply it like any resource pack. Take a hit to see the damage flash, or go underwater for the air row. No command is needed. ## The HUD editor Click the HUD to open its editor, with three modes along the top: | Mode | What it does | | --- | --- | | **Design** (the default) | Tiles for each style: **Hotbar** (Classic, Slots, Rounded, Glass, Minimal, Ornate), **Selection** (Frame, Bold, Corners, Glow, Fill, Underline), **Bars** (Classic, Rounded, Slim, Segmented, Framed) and **Crosshair**, with colour wells and the tray's opacity. Each icon has a click-to-paint grid, and every state of it follows. | | **Paint** | Every sprite on one sheet at its real size, a guide box round each, for pixel work in the [pixel editor](/blocks#the-pixel-editor). The **Parts** rail jumps to a group. Paint in the gaps between sprites does nothing in game. | | **Preview** | Your HUD over a day, cave or Nether backdrop, updated as you work. | ## Screen overlays The layers drawn over the whole screen (**Vignette**, **Nausea**, **Frost rim**, **Spyglass scope**, **Pumpkin blur** and **Underwater tint**) are a second HUD set. Studio's Add asset sheet doesn't offer it yet; it can be made through the [public API](/api-reference) by asking for the `overlays` set. A pack can have one HUD and one set of overlays. ## What's in the exported pack A HUD leaves as the vanilla files it replaces, under `assets/minecraft/textures/gui/sprites/hud/` and `assets/minecraft/textures/gui/sprites/boss_bar/`, with `.png.mcmeta` files for the few sprites that need one. No plugin is involved. ## On Bedrock The HUD is Java-only. The rest of your pack converts as normal. --- Source: https://resourcepack.ai/docs/icons # Icons An icon is a small picture tied to a text character. Put that character anywhere Minecraft draws text (chat, signs, books, item names, scoreboards, holograms) and your picture appears in its place. It's how servers show rank badges, coins, custom emoji and little symbols inside messages. ![Icons made in Studio, used in chat](/images/icons.webp) ## Making one Open a pack, press **Add asset** and pick **Icon**. For the badge in front of a player's name, set **Type** to **Rank tag** instead: see [Rank Tags](/rank-tags). - **Generate**: describe it ("a gold coin", "a crossed sword and shield") and finish it in the pixel editor. - **Blank**: draw it yourself. - **Upload**: bring a PNG. It keeps its shape: set a width or a height (or pick a preset) and the other follows the picture. A picture 32 pixels tall or less starts at its own size. Small pixel art is unforgiving: below about 6 pixels of real detail, an icon stops reading. Get the silhouette right first. ### Which size to pick | Size | How it sits in text | | --- | --- | | **8px** | Fits inside one line of text. The only size guaranteed not to overlap | | **12px** | Blank and Upload only. A readable chat icon that sits on the line | | **16px** | The default for Blank and Upload. Overlaps the lines above and below a little | | **32px** | The default for Generate. A big icon that overlaps neighbouring lines, like a large emoji | | **64px** and **128px** | Generate only. For GUIs, HUDs and screens rather than chat | | **Custom** | Blank and Upload only: any width and height, up to 256 | A generated icon is always square: 8, 16, 32, 64 or 128 pixels. An 8px one has very little room and most come out rough, so use 16 or 32 for anything with detail. For a wide or tall icon, or a 12px one, draw it from blank or upload one. Minecraft's lines of text are about 9 pixels apart and the game doesn't make room for taller icons, so 16 and 32 overlap on purpose. Use 8 or 12 when an icon has to stay inside its line. ### Choosing from 4 versions Every Icon you generate is drawn 4 times, and Studio picks the best one to start you off. On Creator, Studio or a Team, the **Versions** card on its page shows all 4: hover over one to preview it, and click it to use it instead. Switching is free, and the one it replaces stays in the Icon's AI history, so you can always switch back. On the free plan, the card shows that 4 were drawn. With a reference picture of the thing itself, 2 of the 4 are redrawn from your picture and 2 are drawn from a description of it, in no particular order, so you can pick whichever came out best. ### Which character it uses Every icon is drawn in place of one text character. Leave **Character** blank and Studio gives the icon a new character from Unicode's Private Use Area (`U+E000` to `U+F8FF`), a range no real text uses. Or type an existing character (`A`, `❤`) to replace it everywhere text is drawn, for everyone with the pack. A Private Use character shows as a blank box anywhere without your pack. That's expected. ## Seeing it in game On a server running [RP Engine](/testing/plugin), our free plugin, press **Sync** to send the pack to yourself in game. Then press **Send in-game** on the icon's page to get it in your chat, or copy the character from the page and paste it anywhere text appears. Nothing has to be placed or given: an icon works in every message the moment a player has the pack. On [our test server](/testing/test-server), `/sidebar`, `/title`, `/actionbar` and `/bossbar` take any text. Paste an icon into one to see how it sits next to real game text. A plugin sends one like any other text: ```java //  is the icon's character. Its page in Studio shows yours. player.sendMessage(Component.text(" Quest complete")); ``` On a server running [RP Engine](/rp-engine), players can also type icons by name; see [RP Engine icons](/rp-engine/icons). ## Exporting An icon is two things in the `.zip`: ``` assets/minecraft/textures/font/.png assets/minecraft/font/default.json ``` The PNG is the picture. `default.json` is the font file that ties each picture to its character and sets how high it sits on the line. Every icon in the pack shares it. It adds to the default font rather than replacing it, so ordinary text is untouched. Characters are per pack An icon copied into another pack usually keeps its character, but gets a new one if that pack already uses it. Copy the character from the icon's page again after moving it. ## On Bedrock Icons carry over to the `.mcpack`, and the same character shows the same picture on Bedrock. Two differences: - **Every icon is about one line of text tall** on Bedrock, whatever size you gave it. - **Bedrock uses part of the same character range for its own button prompts.** A pack with icons replaces those, so a controller prompt can show blank for a Bedrock player. --- Source: https://resourcepack.ai/docs/importing # Importing Importing turns a Java resource pack `.zip` you already have into a pack in Studio, so you can edit its textures, models, icons, GUIs and sounds here. Use it to carry on with an old pack, or to restyle somebody's pack you have the rights to. Import always **creates a new pack**; it never merges into one you already have. To get pieces of it into another pack afterwards, see [Moving assets between packs](/moving-assets). ## Importing a pack Press Import and pick the zip **Import** is next to **New pack** on the dashboard. The zip is read **in your browser** and nothing is uploaded yet, so even a large pack is quick. Review what was found The review screen lists what will come in and what won't, file by file, with the reason for each file left out. Approve it Only now does anything upload. The pack is created and fills in. If you cancel partway, Studio asks whether to keep or delete what has already arrived. ## What comes in - **Block and item textures**, for anything the game has a texture for. - **Block models**, with their textures, including faces that use vanilla textures. - **Icons**, when the pack's font files say where each one is on its sheet. Up to 256 per import. - **GUI sheets** for the screens Studio knows (chests, furnaces, the inventory and so on). - **Sounds**, when the pack's `sounds.json` names them, since the name decides whether a sound replaces a vanilla one or is new. Up to 64 per import. **Packs with versions inside them** (`overlays` folders for several Minecraft versions) come in as the version the pack itself declares. The other versions' files are set aside and listed. ## What can't come in Reported, never silently dropped: - **Entity, painting and particle sheets.** Nothing in the pack says how to cut them up. - **Core shaders.** - **Blockstate and item definition files.** Studio writes those itself when it exports. - **Audio Minecraft can't play properly.** Anything that isn't mono Ogg Vorbis: Ogg *Opus* files (same `.ogg` extension, but silent in game), stereo `.ogg` files (which don't sound like they come from a place), and other formats. - **OptiFine extensions.** ## Importing a pack you exported from Studio Most of it comes back: shapes, textures and sounds. What doesn't, yet: a model's animations, bones and display settings come back as plain geometry, and per-face block textures return as ordinary model textures. Keep the original pack around rather than treating export-import as a backup loop. --- Source: https://resourcepack.ai/docs/items # Items An Item is the flat picture Minecraft draws for an item: in your hand, in the hotbar, in an inventory and in an item frame. It's pixel art, like a Block, and Studio calls the picture a **sprite**. Use it to redraw a vanilla item (every diamond sword looks like yours) or to make a special item for your server (a quest key, a coin). ![Item sprites made in Studio, in an inventory](/images/items.webp) Want depth? Pick 3D Choosing **3D** under **Shape** makes a 3D item out of cubes instead of a flat sprite, edited in the model editor. See [Models](/models). ## Which kind do you need? A resource pack can't add a brand new item to the game, so every sprite is attached to an item that already exists. How it's attached decides who sees it: | Kind | What changes | Trade-off | | --- | --- | --- | | **Reskin** (Applies to: **Base Item**) | Every copy of that vanilla item, for everyone with the pack | The vanilla look is gone. One reskin per item, per pack | | **Variant** (Applies to: **Custom**) | Only copies handed out with this variant's tag. Ordinary ones look normal | Needs Minecraft 1.21.4 or newer, and a command to hand one out | | **Custom item** (item: **Custom**) | Nothing vanilla. A new-looking item carried on paper | Needs a give command, like any carried model | Use a reskin for a texture pack: every iron sword in the world looks like yours. Use a variant or a custom item on a server: your quest item looks special and everyone else's sword stays a sword. The "tag" a variant uses is **custom_model_data**, a value stored on an item stack that the pack reads to decide which picture to draw. Studio sets it up for you and puts it in the give command. ## Making one Open a pack, press **Add asset** and pick **Item**. Choose the **Item to reskin** (or **Custom** for a custom item), then how it **Applies to**, and keep **Shape** on **2D**. Then either: - **Generate**: describe it, for example "a rune-etched iron key, cold blue glow along the teeth". See [Generating with AI](/generating). - **Blank**: draw it yourself in the pixel editor. - **Upload**: bring a PNG you already have, or a model (`.json` or `.bbmodel`) for a 3D item. Once Studio knows which vanilla item a file is for, its row asks whether it changes **Every one** of that item (a reskin) or **Custom model data only** (a variant), the same choice as **Applies to**. | Size | Notes | | --- | --- | | **16×16** | Vanilla's resolution | | **32×32** | The default for a generated sprite | | **64×64** | Higher-resolution packs | | **128×128** | HD packs: the most detail, still with the pixel-art outline | | **Custom** | Blank only: any size up to 256 | A generated sprite comes in those four sizes only. For any other size, draw it from blank or upload it. On the item's page, **Regenerate** tries the same prompt again and **Edit with AI** changes one thing about the sprite you have, which is usually what you want when only a detail is wrong. ### Choosing from 4 versions Every 2D Item you generate is drawn 4 times, and Studio picks the best one to start you off. On Creator, Studio or a Team, the **Versions** card on its page shows all 4: hover over one to preview it, and click it to use it instead. Switching is free, and the one it replaces stays in the 2D Item's AI history, so you can always switch back. On the free plan, the card shows that 4 were drawn. With a reference picture of the thing itself, 2 of the 4 are redrawn from your picture and 2 are drawn from a description of it, in no particular order, so you can pick whichever came out best. ### How it's held A flat item is held like paper unless you say otherwise: flat and upright. That's wrong for a staff, a wand or a flag. A variant or a custom item has a **Held like** card on its page: | Choice | Held like | | --- | --- | | **Item** | Paper: flat and upright. The default | | **Tool** | A sword: at an angle, the bottom left of the picture in the hand | | **Rod** | A fishing rod: the tool angle turned the other way | For **Tool**, draw the handle in the bottom left and the tip in the top right, as vanilla's swords are. Sync to see the change in game; it's in every export too. A reskin is held the way its vanilla item is, so it has no card. ### Drawing a good sprite Click a sprite to open it in the [pixel editor](/blocks#the-pixel-editor), the same one Blocks use. Two habits help: - **Keep the outline dark and unbroken.** An item is seen small, against both a light inventory and a dark hotbar, and the outline stops it disappearing into either. - **Leave a little room at the edges.** The stack count is drawn over the bottom-right corner, and art that runs to the very edge looks clipped. ## Seeing it in game On a server running [RP Engine](/testing/plugin), our free plugin, press **Sync**: Studio sends the pack straight to you in game. A reskin needs nothing else, since every copy of that item already shows it. Without a plugin, [export](/exporting) the pack and add it like any resource pack. For a variant or a custom item, the item's page has the give command and a **Give in-game** button that hands you one directly. A variant's command looks like this: ``` /give @p iron_sword[minecraft:custom_model_data={strings:["quest_blade"]},minecraft:item_name="Quest Blade"] ``` That string is what makes the item look like yours, so a shop, crate or menu plugin can show it too: give that plugin the vanilla item and the same `custom_model_data` string. An Item is art, not a plugin item: to give it behaviour, an ID or a permission in RP Engine, define it in a [content pack](/rp-engine/items) and point its `texture:` at this picture. The string in `custom_model_data` is made from the item's name, so it can come out long. To pick a shorter one, press the pencil on the item's page and change **Custom Model Data**. Copies handed out before the change stop showing the item, so give them again after you Sync. ## States: a bow that draws back A variant is the vanilla item underneath, so a variant of a bow shoots like a bow and a variant of a shield blocks like one. What you give it is how it looks while it does: the item's page has a **States** card for every item the game draws in more than one way. | Variant of | States | | --- | --- | | Bow | Three drawing stages (from the start, after 0.65 seconds, fully drawn at 0.9) | | Crossbow | Three loading stages, Loaded, and Loaded with a rocket | | Trident | Raised to throw | | Shield | Blocking | | Fishing rod | Cast | | Goat horn | Playing | | Brush | Three brushing stages | Each state switches at the same moment vanilla's does. Leave one empty and it shows the state before it, so a single drawn look is enough for a bow. On a 2D item each state is a picture you upload, fitted to the item's size; on a 3D item each state is another model in the pack. States need Minecraft 1.21.4 or newer, like the variant itself. A reskin (**Base Item**) has states too. A 3D reskin works like a variant. A 2D reskin of a bow, crossbow or fishing rod replaces vanilla's own drawing pictures, so it works on every version, and an empty state shows vanilla's picture. A 2D reskin of a trident, shield, goat horn or brush has no pictures of its own to replace; make it 3D to give it states. A custom item is carried on paper, which has no states. To make your own bow, make a variant of a bow. **A crossbow (or bow) from another pack.** Importing a pack whose crossbow has several models gives you each model as a separate 3D Model on paper, which can't be turned into a crossbow afterwards. Instead, add the main look as an **Item**: **Item to reskin** set to **Crossbow**, **Shape** **3D**, and **Upload** its model (`.json` or `.bbmodel`), as a **Custom** variant or a reskin. Its page then has the **States** card, where each state picks another model in the pack: the pulling and loaded models you imported. Needs Minecraft 1.21.4 or newer. ## Several versions of one item There's no variant switch on a single item. Make each version its own Item: right-click it on the pack page, **Duplicate**, then change the copy with **Edit with AI** (a Christmas version, another colour) or in the editor. Each copy has its own custom_model_data and give command. A reskin is one per item, so extra versions of a reskinned item have to be variants. ## What's in the exported pack In the exported `.zip`, a sprite is a PNG at `assets/minecraft/textures/item/.png`, which is where vanilla looks. For a reskin that's all there is. Variants and custom items also get an item definition under `assets/minecraft/items/`, which maps the custom_model_data tag to the sprite. They need the pack **and** a command: the sprite alone changes nothing until something hands out a tagged item. If you edit an exported pack by hand `textures/item/` and `textures/block/` are different folders to the game. A sprite in the wrong one does nothing at all, with no error. Studio files them correctly for you. ## On Bedrock Reskins carry over to the Bedrock `.mcpack`, renamed where Bedrock uses a different name (`golden_apple` is `apple_golden`, `wooden_sword` is `wood_sword`). Variants don't: custom_model_data is Java-only. A custom item comes across as its sprite (or its model's icon) on a server with Geyser; see [Bedrock and Geyser](/bedrock). --- Source: https://resourcepack.ai/docs/loading-screens # Loading Screens A Loading Screen restyles the screen Minecraft shows while resource packs load: normally red, with the Mojang Studios logo and a white bar. Yours can have its own colours, your server's name and logo, an effect like falling snow or rising embers, and a progress bar to match. ![Six Loading Screens made in Studio: a pastel marshmallow, a Halloween pumpkin, a beach sunset, a winter snowflake, an arcade joystick and a racing flag](/images/loading-screens.webp) ## Making one Press **Add asset** and pick the **Loading Screen** tab. Either: - **Describe it** ("a spooky Halloween server called Grimfall"). Studio designs the colours, effect, words and bar, which costs 5 AI Credits and takes a few seconds; or - **Pick a look**, which is free: Winter Night, Nether, Starfield, Firefly Forest, Thunderstorm, Royal Gold, Ocean, Clean, or Recoloured (Minecraft's own screen and logo in a colour of your choosing). The name you give it becomes the title on the screen. Either way it opens in the editor. ## The editor The screen plays live, as the game draws it: the effects move and the bar fills. A Loading Screen is made of **layers**, listed on the left; click one (or click it on the screen) to change it on the right. Press **+** (or N) to add a layer, drag layers in the list to reorder them, and press Delete to remove one. - **Words**: a title, or a smaller line such as your server's address, as many as six with the pictures. Each has its own font (Chunky, the default; Classic; or Tiny, which keeps lower case), size, colour or two-colour gradient, outline, bold and letter spacing. They stack top to bottom in the order listed. - **Pictures**: your logo as pixel art, up to two. Best up to 128 by 64 pixels and 12 colours; bigger ones are shrunk to fit. - **Effects**: snow, rain, stars, embers, sparkles, fireflies, bubbles, petals, hearts or confetti, in any colour and amount, up to three at once. - **Minecraft's logo**: keep the Mojang Studios logo and restyle the screen round it. - **Background**: one colour, a gradient (top to bottom, out from the middle, or corner to corner), or a pattern of two colours (stripes, a checkerboard, or a sunburst that slowly turns), with an optional glow behind the logo. - **Bar**: the frame and fill colours, solid, a gradient along the bar, moving stripes or segments, and an optional colour for its empty part. - **Logo**: the size of the whole logo, how high it sits, the pictures beside the words instead of above them, and a shadow under everything, from a drop shadow to a deep 3D edge. - **Looks**: switch to another ready-made style. Your words and pictures stay. - **Edit with AI**: say what to change ("make it purple", "add fireflies") and the layers change. Nothing is saved until you press Save, so you can undo it. A pack shows one Loading Screen. If it has several, the card marked **Shown** is the one in the pack; press **Use this** on another to switch. ## When players see it It works on **Minecraft 26.1, 26.2 and 26.3**. Older versions see Minecraft's own screen. On 26.1 the effect stands still, because that version gives the loading screen no clock; it moves on 26.2 and 26.3. A player sees it whenever the game reloads resources while your pack is already loaded: - pressing F3+T; - turning packs on or off in the Resource Packs menu; - a server sending a second pack, or leaving a server whose pack is then taken off. When a player joins your server, the load starts on Minecraft's red screen, because the game hasn't read your pack yet, and switches to yours part-way through. The very first screen when the game starts is always Minecraft's own. ## How it works Minecraft reads the Mojang logo from its own files only, so a resource pack can't simply replace it. Instead your pack overrides the two shaders the loading screen is drawn with, recognises the background, the logo and the bar by where they are, and paints your design over them. Everything else drawn with those shaders is left exactly as it was. The shaders only load on the versions above, so a newer or older Minecraft falls back to the normal screen rather than breaking your pack. ## Sharing it **Publish** in the editor's header puts it in the [Gallery](https://resourcepack.ai/gallery), where it plays live on its page. Anybody can add it to a pack of their own, where it becomes that pack's Loading Screen, and edit it like any other; pictures in its logo go with it. --- Source: https://resourcepack.ai/docs/mcgui # MC GUI MC GUI is a server plugin that puts HTML pages in the game. Put a page in a folder and players see it on a wall they can walk up to and click, or fullscreen, where they point with their mouse and click like on a computer. Use it for menus, shops, server selectors, rules boards and minigames that need more than a chest or a dialog can show. Vanilla clients, no mods. ![Four MC GUI pages in game](/images/mcgui.webp) - **Server owners** write pages in HTML and CSS (or make them in the free editor at [mcgui.dev](https://mcgui.dev)), and give their buttons commands, links and sounds. No code. - **Developers** open those pages from their own plugin and hear every click as an event, or draw their own pictures on walls and fullscreen. No browser runs on the server. MC GUI has its own HTML and CSS renderer, so a page is **static** HTML and CSS. Links, commands, hover states, scrolling, sounds and form controls are made to work in game instead. For games, a page can also run JavaScript that draws on a `` (see [Scripts](#scripts)). MC GUI, a dialog or a chest GUI? A [chest GUI](/guis) is a container screen with new art, holding items you can pick up. A dialog ([Dialog Engine](/dialog-engine) or [RP Engine's](/rp-engine/dialogs)) is the game's own menu of buttons and text boxes. MC GUI is a whole web page with a mouse pointer, as rich as you can write in HTML. [Which plugin for menus](/plugins#which-plugin-for-menus) compares them. ## Installing Get the jar Download MC GUI from [resourcepack.ai/mcgui](https://resourcepack.ai/mcgui) or [SpigotMC](https://www.spigotmc.org/resources/139931/). Drop it in Put the jar in `plugins/` and restart. It runs on **Spigot, Paper or Folia 1.21.11 or newer**, one jar for all three, and needs **Java 21** (Java 25 for 26.x). [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) is optional. Players need nothing installed. Try an example Run `/mcgui open market`. Sneak to get up. What it makes: ``` plugins/MCGUI/ config.yml pages/ ← your pages: menu, rules, shop and market to start from sounds/ ← .ogg files to put in the pack cursors/ ← .png pointers to put in the pack screens.yml ← where wall screens are placed ``` What talks to the internet `update-check` asks SpigotMC for the latest version. `telemetry` sends an anonymous count every 30 seconds: a random id, the number of players online and the names of plugins that depend on MC GUI; while it is on, `/mcgui import` also says which server is importing. A page can load fonts, stylesheets and images from the web while `allow-web` is on. Each can be turned off in `config.yml`. ## Your first page Make a file `plugins/MCGUI/pages/hello.html`: ```html

Hello, {player}

{online} players online.

``` Open it Run `/mcgui open hello`. Pages reload by themselves within a second of you saving the file (`live-reload`), so leave it open and keep editing. Put it on a wall Look at the side of a block and run `/mcgui place hello 4 3`. That block becomes the top-left corner of a screen 4 maps wide and 3 tall. ## Pages from mcgui.dev [mcgui.dev](https://mcgui.dev) is a free editor for these pages. Editing, previewing and sending a page need no account; only the AI asks you to sign in. Your projects are kept in your browser. ![The mcgui.dev editor](/images/mcgui-editor.webp) There is no palette of buttons and pictures to drag in. You make a page by describing it to the AI, starting from a template, or writing the HTML, and then wire up its buttons by clicking them. Along the top: | Control | What it does | | --- | --- | | **New** | A blank project, or one of your recent ones | | **Templates** | Start from Server menu, Shop, Server selector, Leaderboard, Rules or Style guide | | **Map** | Every page in the project as a card, with where each button goes | | **Page** | One page. Click anything on it to make it a link: to another page, **Go back**, **Close the page** or **Run a command**. **Try it** lets you click through it as a player would | | **Code** | The HTML and CSS beside a live preview. The line under the code says what won't work in MC GUI | | The AI bar | Describe a new page, or a change to the open one. **Minecraft** or **Modern** is the look it designs in, and you can attach a sketch or screenshot for it to copy (or paste one with Ctrl+V). Each request costs 10 AI Credits from your ResourcePack AI account | | **Export** | Download everything as a .zip for `plugins/MCGUI/pages/`, or just the open page | | **Send to server** | Gives you a code for `/mcgui import` | In the pages list, **+** makes a new page: name it, say what's on it and press **Make it with AI**, or start from Blank, Cards, List, Text, Two columns or Confirm. Each page's menu can copy the `/mcgui open` command that opens it. The same editor is in Studio as a **Custom GUI**, kept in a pack on its GUIs tab. Press **Send to server** and you get an eight-letter code. On the server: ``` /mcgui import ``` That writes the project's pages, stylesheets and pictures into the pages folder, replacing files of the same name, and tells you how to open them. Importing the same project again removes the files it no longer has, unless they were changed on the server since. Any picture a page uses as a [cursor](#cursors) is copied into the cursors folder, and the server needs a restart before it shows. A page made on mcgui.dev is drawn with a faint mark: some blocks of plain colour are one shade bluer, in a pattern mcgui.dev can read back from a screenshot. It holds nothing about the player or the server. `builder-mark: false` draws every page exactly as written. ## Fullscreen pages `/mcgui open ` sits the player down in front of the page. Their camera locks onto it and only they see it; the rest of the world goes on around them. | Control | Does | | --- | --- | | Mouse | Moves the pointer | | Left or right button | Clicks | | Wheel, or W and S | Scrolls | | F | Goes back a page | | Sneak | Gets up | | Any key a page gives a `data-key` | Clicks that element | They are put back exactly where they stood, facing the same way. Anything that hurts them, a teleport, a world change or death also gets them up. The page fills the whole window, whatever its shape and the player's field of view, and the pointer moves as fast as their mouse. Fullscreen pages need the resource pack: a player without it is told so and offered the pack again, rather than seated. ### Size A fullscreen page is 16 maps by 9 by default (`views.size`), laid out 576 CSS pixels tall (`views.height`), so at the usual window shape it is 1024 CSS pixels wide. A page can set its own with `ui:size` and `ui:height` ([page settings](#page-settings)). The size is also the player's frame rate: every map on screen is drawn on its own. 16×9 is about one map pixel per screen pixel in a 1080p window. **14×8** gives about 25% more FPS with text barely softer; **12×7** or **11×6** (50 to 80% more) suit pages of big buttons and pictures. Avoid 8×5, which is stretched in a 16:9 window. ### Pointer speed The pointer moves a fixed distance for each step the mouse reports, like a desktop pointer, whatever the player's Minecraft sensitivity. At the default `views.pointer-speed: 1.0`, crossing the page takes as much hand movement as crossing a 1920-pixel screen at Windows' default speed. Each player can scale theirs with `/mcgui pointer <0.25 to 4>`. When a player opens a Minecraft screen over a page (chat, the inventory, the pause menu) the game frees the mouse and their own cursor shows too, until they close it. The page's pointer hides itself for the pause menu while the game's Menu Background Blur is 1 or more, which is the default. ## Wall screens ``` /mcgui place [cols] [rows] [name] [shared] ``` Look at the side of a block: it becomes the top-left corner. The screen is `cols` maps wide and `rows` tall, in invisible frames only players' games know about, so nothing in the world changes. Players point at it with their crosshair: left-click clicks the page, the wheel scrolls it, and right-click sits them down at that page fullscreen (`walls.right-click-fullscreen`). - **Each player browses their own copy** of a wall's page: one player opening a tab does not open it for everybody. Place it `shared` and everyone sees the same one; commands, messages and links still act for whoever clicked, with placeholders filled in for them. - `/mcgui remove [name]` takes one down, or the one you look at. Screens are kept in `screens.yml` and come back on restart. A screen in a world loaded later (by a multiworld plugin) goes up when that world loads. - A screen is only sent to players within `screens.view-distance` blocks (48), and can be clicked from `screens.reach` (8). - Screens showing the same page share their maps, so one page on many screens costs players about what one does. Many different pages in view is what lowers their frame rate. ## Overlays A page with an overlay setting is drawn on nothing instead of white: ```html ``` Leave `html` and `body` transparent and put the page in a panel. Fullscreen, the player sees the world round the panel under that tint. Add `blur` to blur the world as the game blurs it behind a menu: ```html ``` **To remove the tint and the blur**, set `content="none"`: the world shows clear round the panel. Pages from mcgui.dev may also darken or blur the background in their CSS (a dark `background` or `backdrop-filter: blur()` on a full-page box); take that out too. Opening an overlay does not move the player's view at all. The world round the panel is the picture of it their game took as it opened, so it stays still while the pointer moves, and they are back exactly where they were when they close it. That needs a 1.21.11 or newer client and the pack; otherwise the world shows live round the panel. On a wall, the wall behind shows through. `market-overlay` and `market-blur` in the examples are the market as an overlay. ## The sidebar, boss bars and action bar While a player has a page open (fullscreen or an overlay), MC GUI hides the sidebar scoreboard, boss bars and action bar that other plugins draw, and puts them back when the page closes: ```yaml views: hide-hud: scoreboard: true boss-bars: true action-bar: true ``` It is done for that player alone, and works with TAB, ProtocolLib, PacketEvents and anything else that draws them. When the page closes they get each one back as it is now. Turn one off to keep a plugin's sidebar, bar or action bar on screen at pages. The tab list, chat, titles and the text under names are never touched, and a HUD drawn with resource pack glyphs stays. These settings are read when the server starts. ## In a page | Write | In game | | --- | --- | | `` | Goes to another page in the folder; `#id` scrolls to it | | `data-command="spawn"` | Runs a command as the player | | `data-console="give {player} bread"` | Runs a command as the console. Not run if a filled-in value has a space or `;` in it (a nickname, say), which is logged | | `data-message="Hi {player}"` | Sends the player a chat message, in MiniMessage | | `data-action="close"` | Closes the page. Also `back`, `reload`, `top`, `page:shop` | | `data-close` | With a command: closes the page after running it | | `data-event="buy"` | Nothing by itself: a plugin hears it ([for developers](#for-developers)) | | `data-sound="block.note_block.pling 1 1.5"` | The sound a click on it makes: ` [volume] [pitch]`, or `none` | | `data-hover-sound="ui.button.click 0.1 2"` | Plays when the pointer comes onto it | | `data-key="1"` | Fullscreen, pressing that key clicks it: `w` `a` `s` `d`, `space`, `sprint`, `f`, `q`, `1` to `9` (several with spaces) | | `` | A player's face with their hat layer, crisp at any size. Any name or UUID works (`head:Notch`) | | `href="https://..."` | Sends the link to chat, where it can be clicked | | `:hover`, `:active` | Work, as the pointer moves and clicks | | `
`, checkboxes, radio buttons | Open and tick when clicked | | ``, `` | A click picks the next option, sets the slider where it lands, or steps the number down (left half) or up (right half) | A page's own `data-key` wins over what the key does by default. The wheel also moves the hotbar, so a page can use any six of the number keys. Players cannot type into a text box: there is no keyboard to type with. ### Text on hover (tooltips) The `title` attribute shows nothing. Make a tooltip with CSS: put the text inside the element, hidden, and show it on `:hover`. `:hover` is also how you give a button a hover effect. ```html ``` The `market` example page does this for every item on its shelves. ### Forms A submit button inside a form runs the form's command with each field's value filled in as `{form.}`: ```html
``` A form can use `data-console` or `data-message` the same way, and any element's command can use `{form.}` too, from the form it is in or the whole page. ### Placeholders Filled in for each player, in text and in attributes: | Placeholder | Is | | --- | --- | | `{player}` `{uuid}` | Their name and UUID | | `{world}` `{x}` `{y}` `{z}` | Where they are | | `{online}` `{max}` | Players online, and the most allowed | | `{health}` `{level}` | Their health and XP level | | `%...%` | Any [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) placeholder, when it is installed | They are filled in once as the page opens. To keep them current, give the page `ui:refresh` ([page settings](#page-settings)). ### Page settings All optional, in the page's ``: ```html ``` ## Sounds A sound is any the game has, by its id (`entity.experience_orb.pickup`), or your own: put an `.ogg` in `plugins/MCGUI/sounds/` and restart, and it goes into the pack named after its path. `sounds/menu/open.ogg` plays as `uiengine:menu/open`, from a page, `/playsound` or any plugin. Names are lower case. Only the player who clicked hears a page's sounds. ## Cursors The pointer is an arrow, a hand over anything clickable, a text caret, or nothing, as the page's CSS `cursor` says (`default`, `pointer`, `text`, `none`). For one of your own, put a PNG in `plugins/MCGUI/cursors/` and restart: it goes into the pack under its file name, and a page asks for it the way a web page does. ```css body { cursor: url(arrow.png), default; } .button { cursor: url(hand.png) 6 0, pointer; } .locked { cursor: url(no.png) 8 8, default; } ``` The two numbers are the pixel that points, in the picture's own pixels (top left if left out). The keyword after it is what players see if the cursor is not in the pack yet. 16 pixels tall is the arrow's size; up to 32 is drawn bigger, and taller is scaled to 32. ## What pages can use **CSS:** every selector and combinator, `:not` `:is` `:where`, `:hover` `:active`, `::before` `::after` `::marker`, the cascade with `!important`, variables, `calc()` `min()` `max()` `clamp()`, `@media`, `@import`, `@font-face` (TTF and OTF, and Google Fonts links), block and inline layout, flexbox, grid (`repeat(auto-fill, minmax())`, `fr`, areas), tables, absolute, fixed and relative positioning, `z-index`, `overflow` and scrolling, `border-radius`, borders, `box-shadow`, `text-shadow`, linear, radial and conic gradients, `background-clip: text`, background images, `opacity`, `transform`, `filter`, `backdrop-filter: blur()`, `clip-path` (`polygon()`, `circle()`, `ellipse()` and `inset()`), `object-fit`, `text-overflow: ellipsis`, `-webkit-line-clamp`, and animations and transitions (`@keyframes`, `animation`, `transition`). **Pictures:** PNG, JPEG, GIF, SVG files and inline SVG. Page CSS styles what is inside an inline SVG too: `fill`, `stroke` and the rest, `:hover` rules included. **Animated GIFs** play, as an ``, as a CSS `background-image` and through a script's `drawImage`, with their own timing and looping. One that doesn't loop stops on its last frame. A few things to know: - A page is redrawn `animation-fps` times a second (10 by default, set in `config.yml`), so a GIF faster than that skips frames. - Like a CSS animation, a GIF costs CPU for as long as it's on screen. Keep them small on pages lots of players have open. - Each GIF is held in memory to at most 64 MB decoded, and 1024 frames. A bigger one drops frames evenly and keeps its timing. A GIF where even two frames wouldn't fit shows only its first frame. **On an overlay page** the world shows through, and each pixel is either drawn or not: colour less than half opaque with only the world behind it isn't drawn in game (a browser draws it faint), and colour at half or more is drawn solid. Use 0.5 opacity or more for anything that must show, like a thin border. **Fonts:** Inter (`sans-serif` and every system font name), Source Serif 4 (`serif`), JetBrains Mono (`monospace`), `Minecraft` (the game's own letters) and `Monocraft` are built in, for Latin letters (Inter also has Greek and Cyrillic). For Thai, Chinese, Japanese, Korean, Arabic or another script, load a font that has it, or its letters can come out as boxes: ```html ``` A `.ttf` or `.otf` in the pages folder works too, with `@font-face`. **Not supported:** WOFF fonts, WebP pictures, video, iframes, floats (a floated box stays where it is), typing into inputs, and scripts changing the page's HTML or CSS (a script draws on a canvas: see [Scripts](#scripts)). Files are read from the pages folder only. With `allow-web` a page can also load stylesheets, fonts and pictures from the web, but not from the server's own machine or network unless `allow-private-hosts` is on. Pages load in the background, so a slow one never holds up the server. ## Scripts A page can run JavaScript that draws on a ``, for games and anything drawn fresh every frame. Most pages don't need one: menus, shops, forms, tabs and hover effects all work without a script. ```html ``` | A script has | | |---|---| | Drawing | The canvas 2D context: rectangles, paths, arcs, text, `drawImage`, gradients, transforms, clipping, alpha and line dashes. Not yet: `getImageData`, `putImageData`, patterns, shadows and filters. | | Time | `requestAnimationFrame` (20 frames a second, up to 30 with ``), `setTimeout`, `setInterval`, `performance.now()` and promises. | | Keys | `keydown` and `keyup`, with `e.key` one of `"w"` `"a"` `"s"` `"d"`, `" "` (jump), `"Control"` (sprint), `"q"` and `"1"` to `"9"`. Those are the keys a seated player has. F still goes back and sneaking still closes the page. | | Mouse | `mousemove`, `mousedown`, `mouseup` and `click` on the canvas, with `offsetX` and `offsetY` in CSS pixels. | | Pictures | `new Image()` with a picture from the pages folder, or an `` on the page, for `drawImage`. An animated GIF draws whichever frame it has reached, so drawing it every frame plays it. | | Minecraft | `mcgui.sound("entity.experience_orb.pickup 1 1.5")` plays a sound to the player, `mcgui.command("spawn")` runs a command as them (only from their own click or key press), and `mcgui.player` is their name. | A script can't change the page's HTML or CSS, so draw anything that changes (a score, a timer, game over) on the canvas. Scripts have no network access and load from the pages folder only. `mcgui.command` only runs while the player's own click or key press is being handled. Asked for at any other moment (as the page opens, or from a timer), the command is not run and the console says why, so a page can never run commands as whoever opens it without them doing anything. To give a reward at the end of a game, draw a "Claim" button and run the command when it is clicked. Each player gets their own copy of the script, and scripts never run on the server's main thread. A frame that takes longer than 250 ms stops the script, and errors are written to the console with the page and line. Newer JavaScript (`class`, `...` spread, `async` and `await`) is converted the first time the page opens, which takes a moment; plain functions and `let` run straight away. The script engine isn't part of the plugin's jar. The first time a page with a script opens, MC GUI downloads it once (2.4 MB) from `cdn.resourcepack.ai`, checks it, and keeps it in `plugins/MCGUI/libs/`. If your server has no internet access, download `https://cdn.resourcepack.ai/MCGUI-scripts-.jar` (the version is MC GUI's) and put it in that folder yourself. ## Fast pages Pages are drawn off the server's main thread. A hover is quick when only the part of the page that changed has to be drawn again, and quicker still when it was drawn before the pointer got there, which MC GUI does for the hovers nearest the pointer. To keep it that way: - **Animate `opacity`, colours, `transform`, `filter` and shadows**, not `width`, `height`, `margin`, `top` or `font-size`, which lay the whole page out again every frame. - **Keep what moves small.** A spinner costs little; a whole panel that bobs is drawn again whole every frame. A `transition` or `animation` costs nothing while it is not running, and one that repeats for ever is drawn once for everybody watching. - **Avoid `:hover` with `+` or `~`** (`.card:hover + .label`): that stops hovers being drawn ahead. Put what changes inside the hovered element (`.card:hover .label`). - **Blur is the costliest thing to draw.** Keep `filter: blur()` and `backdrop-filter` off large areas near things players hover. A blurred background box with nothing inside it is blurred once and kept. - **Keep a player's own values away from what they hover.** Where nothing personal is in reach, one drawing of a hover serves every player. `/mcgui stats` shows what the plugin costs the server right now: its share of each tick, how long pictures took to draw, and its threads. A picture that takes more than `render-timeout` seconds of CPU (2) is given up and reported, so one heavy page cannot hold a thread for good; raise it for very large pages. ## The resource pack With the pack, maps show full colour, smoothly scaled, a fullscreen page fills the window and the pointer follows the mouse every frame. Pages a player opens need it; wall screens work without it, in dithered map colours. MC GUI builds the pack at start (with your sounds and cursors in it) and, under `resource-pack`: | `mode` | Does | | --- | --- | | `upload` (default) | Uploads the pack to ResourcePack AI's free pack host, `packs.resourcepack.ai`, and players download it from there. Nothing to open or set up | | `serve` | Serves `pack.zip` itself on `port`; set `public-url` to an address players can reach, such as `http://play.example.com:25602/pack.zip`, and open that port | | `external` | Serves nothing: host `plugins/MCGUI/pack.zip` yourself and set `public-url`, or merge it into another plugin's pack (ItemsAdder, Nexo) and leave `public-url` blank. The pack is also unpacked into `plugins/MCGUI/pack/` for plugins that merge folders: for ItemsAdder, add `MCGUI/pack` under `resource-pack.zip.merge_other_plugins_resourcepacks_folders` in its `config.yml` and run `/iazip`. **Merge again after every MC GUI update**: an old merged pack draws pages wrong, often in the wrong colours | | `off` | No pack: walls show plain map colours, and pages do not open | With `upload`, the pack is only uploaded again when it changes, it is kept for as long as your server uses it (one nothing has used for 30 days is deleted), and only the Minecraft client can download it. If an upload fails, MC GUI serves the pack itself on `port` and `public-url` until it works, and the console says so. Upgrading from 0.5.2 or older Your `config.yml` may still say `mode: serve` with a blank `public-url`, which sends players `127.0.0.1`. Set `mode: upload` and restart. `required: true` makes the pack required, so a player who declines it is disconnected, and `prompt` is the line their game shows when it asks. `/mcgui pack` sends it again. A restart is needed after adding sounds or cursors, or changing anything under `resource-pack`. MC GUI's pack replaces the game's text shader, as HUD and text-effect plugins' packs do (BetterHud, HUDEngine, ItemsAdder's text effects, Oraxen's animated glyphs), and a game keeps only one copy. **MC GUI merges the two**: at startup it reads the other plugin's pack (or the server's own, `resource-pack` in `server.properties`) and merges that text shader into its own, so both work. The console says `Shaders Merged with ..., so both draw`. A plugin that writes its pack only after MC GUI starts (Nexo, ItemsAdder and other pack plugins do) is merged within a minute of writing it, and players online are sent MC GUI's pack again, so a shader change needs one restart (or the plugin's own reload command). With `mode: external` MC GUI cannot resend its pack, so there it is merged on the next restart, and the console says when one turns up. With two such plugins at once nothing is merged, and the console names them. `resource-pack.merge-shaders: false` turns merging off. Even unmerged, another plugin's shader beside MC GUI's never stops the pack loading. If MC GUI's pack loses anyway, pages still hide the sidebar, boss bars and action bar from the server side ([The sidebar, boss bars and action bar](#the-sidebar-boss-bars-and-action-bar)). ## If pages are slow or don't show | What happens | Why, and what to do | | --- | --- | | Low FPS while a page is open | Every map on screen costs frame time, so a smaller page is faster. Set `views.size` to `14x8` (about 25% more FPS) or `12x7` (50% or more), or `ui:size` on one page. See [Size](#size) | | The page flashes, then closes or shows wrong | Another plugin's resource pack replaced MC GUI's shaders. When MC GUI sends its own pack, it sends it again on top before the next page (a short reload), so open the page again. If you merged MC GUI's pack into another plugin's, merge it again after every MC GUI update, and check what MC GUI says about shaders in the console at startup | | Part of a page is missing on an overlay page (a faint border, a see-through panel) | Colour under half opaque with only the world behind it isn't drawn in game. Use 0.5 opacity or more ([What pages can use](#what-pages-can-use)) | | "Your game could not load the resource pack of this server" | The pack failed to load for that player, often a merged pack. The console says why | | "This menu can't be shown while shaders are on" | The player has Iris or OptiFine shaders on. Shader packs replace what MC GUI draws with, so they need to turn shaders off | | Bedrock players can't open pages | Pages are Java only. Bedrock players see wall screens in plain map colours | | Letters show as boxes | The built-in fonts lack that script. Load one that has it ([Fonts](#what-pages-can-use)) | | A page takes long to open | Leave `network-compression-threshold` in `server.properties` at 256. To find where the time goes, run `/mcgui debug trace on`, have them open it a few times, then send us the `Open trace:` lines from `logs/latest.log` | ## Commands `/gui` and `/ui` work as well as `/mcgui`, unless another plugin has them (`gui-alias: false` or `ui-alias: false` in `config.yml`). | Command | Does | | --- | --- | | `/mcgui open [player]` | Opens a page fullscreen | | `/mcgui close [player]` | Closes it | | `/mcgui place [cols] [rows] [name] [shared]` | Puts a page on the wall you look at | | `/mcgui remove [name]` | Takes a wall screen down, or the one you look at | | `/mcgui list` | Every page, and where every screen is | | `/mcgui reload` | Reads the config and every page again | | `/mcgui import ` | Brings in pages from [mcgui.dev](#pages-from-mcguidev) | | `/mcgui test wall\|view [cols] [rows] [player]` | A test picture on the wall you look at, or fullscreen | | `/mcgui fov ` | Tells the server your field of view, which it cannot read | | `/mcgui pointer [speed]` | Your pointer speed, 0.25 to 4 times the server's | | `/mcgui pack` | Sends you the resource pack again | | `/mcgui stats` | What the plugin costs the server now (`stats json` for one line of JSON) | | `/mcgui clear` | Removes every test wall | | `/mcgui debug trace on\|off` | Logs where the time went each time that player opens a page (see [If pages are slow or don't show](#if-pages-are-slow-or-dont-show)). `debug point`, `click`, `scroll` and `close` drive their open page from the console | ## Permissions Each command has its own node, so you can hand out one without the rest. Pointing a command at another player needs that command's `.others` node too. | Node | Allows | Default | | --- | --- | --- | | `mcgui.open` | `/mcgui open ` for yourself | op | | `mcgui.open.others` | Opening a page for somebody else; also grants `mcgui.close.others` | op | | `mcgui.close.others` | `/mcgui close ` | op | | `mcgui.place` | `/mcgui place` | op | | `mcgui.remove` | `/mcgui remove` | op | | `mcgui.list` | `/mcgui list` | op | | `mcgui.reload` | `/mcgui reload` | op | | `mcgui.import` | `/mcgui import`, which writes files into the pages folder | op | | `mcgui.test` | `/mcgui test` for yourself | op | | `mcgui.test.others` | `/mcgui test` for somebody else | op | | `mcgui.stats` | `/mcgui stats` | op | | `mcgui.clear` | `/mcgui clear` | op | | `mcgui.debug` | `/mcgui debug` on your own page | op | | `mcgui.debug.others` | `/mcgui debug` on somebody else | op | | `mcgui.fov` | `/mcgui fov` | everyone | | `mcgui.pointer` | `/mcgui pointer` | everyone | | `mcgui.pack` | `/mcgui pack` | everyone | | `mcgui.update` | Being told in chat when a new version is out | op | | `mcgui.admin` | All of the above | op | Closing your own page needs no permission, just as sneaking out of it needs none. A page's buttons run commands as the player who clicked, so they still need permission for those commands; `data-console` runs as the console and does not. ## Config The settings most servers touch, in `plugins/MCGUI/config.yml`. Every one is explained in the file itself. | Key | Default | Does | | --- | --- | --- | | `pages-folder` | `pages` | Where pages are read from | | `live-reload` | `true` | Shows a changed page within a second of saving it | | `allow-web` | `true` | Lets pages load fonts, stylesheets and pictures from the web | | `views.size` | `16x9` | Fullscreen size in maps, unless a page sets its own | | `views.pointer-speed` | `1.0` | How far the pointer moves for the mouse | | `views.hide-hud.scoreboard`, `.boss-bars`, `.action-bar` | `true` | Hide that part of other plugins' HUD while a page is open ([more](#the-sidebar-boss-bars-and-action-bar)) | | `walls.right-click-fullscreen` | `true` | Right-clicking a wall screen opens its page fullscreen | | `screens.view-distance` | `48` | Blocks from a wall screen beyond which it is not sent | | `resource-pack.mode` | `upload` | See [The resource pack](#the-resource-pack) | | `resource-pack.public-url` | blank | The pack's address for players (`serve` and `external`) | | `render-timeout` | `2` | Seconds of CPU a picture may take before it is given up | | `cpu-threads` | `0` | Threads for drawing pages; 0 means the cores minus one | | `builder-mark` | `true` | Draws the [mcgui.dev mark](#pages-from-mcguidev) on pages made there | | `telemetry` | `true` | The anonymous usage count | | `update-check` | `true` | Asks SpigotMC for new versions | `/mcgui reload` reads the config again, except the resource pack, screens and threads, which need a restart. ## For developers Add `depend: [MCGUI]` to your `plugin.yml` and compile against MC GUI, never shading it: it owns the pack, the map ids and the seats, so there is one copy on the server. It is published from its [GitHub repository](https://github.com/resourcepack-ai/mcgui) through JitPack: ```groovy repositories { maven { url 'https://jitpack.io' } } dependencies { compileOnly 'com.github.resourcepack-ai:mcgui:' } ``` ### Pages ```java MCGUI.open(player, "menu"); // pages/menu.html, fullscreen MCGUI.close(player); MCGUI.page(player); // the page they have open, or null MCGUI.exists("menu"); ``` What players do on pages comes as Bukkit events: `PageClickEvent` (cancellable, before a click acts, with the element's attributes and the form's values), `PageOpenEvent` and `PageCloseEvent`. An element with a `data-event` does nothing but fire the click, so a page can hand a button to your plugin: ```html ``` ```java @EventHandler public void onClick(PageClickEvent e) { if ("buy".equals(e.getEvent())) shop.buy(e.getPlayer(), e.getAttribute("data-item")); } ``` ### Your own pictures Under the pages is a framework any plugin can draw with, from anything that makes a `BufferedImage`: ```java UIFramework engine = UIFramework.get(); Canvas canvas = engine.canvas(4, 3); // 512 x 384 pixels canvas.draw(image, 0, 0); // only changed tiles are sent again engine.placeWall(topLeft, BlockFace.SOUTH, 4, 3, viewer -> canvas); engine.openView(player, () -> canvas, ViewOptions.DEFAULT); ``` `WallContent` and `ViewContent` have default methods for looking, pointing, clicking, scrolling, keys and chat: implement the ones you need. Every callback runs on the server thread, and a wall can show each viewer a canvas of their own. `canvas.transparency(true)` lets the world show through where a picture is see-through, and `ViewOptions.DEFAULT.blur(true)` blurs it. A view hides the sidebar, boss bars and action bar as the server's `views.hide-hud` says, unless its options choose: `ViewOptions.DEFAULT.hud(HudParts.NONE)` leaves them all on screen, and `ViewOptions.DEFAULT.hud(HudParts.ALL.actionBar(false))` hides all but the action bar. The [examples](https://github.com/resourcepack-ai/mcgui/tree/main/examples) are whole plugins built this way: an arcade of games on cabinets and fullscreen, a live world map, and pages in the game's own look. ## Support Ask in [Discord](https://resourcepack.ai/discord), or open an issue on [GitHub](https://github.com/resourcepack-ai/mcgui/issues). MC GUI is open source under the AGPL-3.0, with a few extra terms in [NOTICE.md](https://github.com/resourcepack-ai/mcgui/blob/main/NOTICE.md). --- Source: https://resourcepack.ai/docs/mobs # Mobs A Mob is a custom creature for your server: a golem boss, a raccoon, a beetle. It's a 3D Model that walks around and fights. You can generate one from words, or convert a model you already have, and then choose how it behaves, how tough it is, which animation plays when, what it sounds like, what special attacks it has and what it drops. ![Mobs made in Studio: a cake golem, a baby dragon, a pumpkin reaper, a cave spider, a crystal penguin and a raccoon](/images/mobs.webp) Mobs need the [RP Engine](/rp-engine) plugin, 0.2.51 or newer, on your server. Our [test server](/testing/test-server) has it. ## Generating one from words The quickest way to a mob is to describe it. 1. On the pack page, press **Add asset**, stay on the **Model** tab, and set **What is it** to **Mob**. 2. Describe the creature: *"a waffle and cake golem boss with a crocodile jaw"*, *"a raccoon"*, *"a purple cave spider"*. A reference picture works here as it does for any model. 3. Press **Generate** (about 113 credits; the exact price is shown under the prompt). It takes roughly 7 to 18 minutes and makes everything in one run: the model, with its head, jaw, legs, tail and wings as separate moving parts; its animations (idle, walk, attack, hurt and death); and its own sounds (an idle call, a hurt yelp, a death cry and an attack). Its card says it's generating, then animating. If a part of the run fails, you keep the rest and aren't charged for the part that failed: a mob whose animating failed has no animations, and a sound that couldn't be made keeps the vanilla one. The mob editor says what went wrong, and **Animate with AI** or **Generate sounds with AI** tries again. ## Making one by hand 1. **Make the model.** Generate, upload or build it, as on the [Models](/models) page. Give it bones and animations (walk, idle, attack) in the model editor's Animate mode, because a mob plays them by state. 2. **Convert it.** On the model's page, press **Convert** in the header, or right-click the model's card and choose **Convert to…**, then **Mob**. The mob editor opens straight away. From then on it's on the pack's **Mobs** tab rather than under Models. 3. **Set it up.** A new mob already works: a hostile mob with 20 health. Change what you need and it saves on its own. ## Animate with AI For a mob you converted from a model. It's at the foot of the mob editor's left column and costs about 25 credits. It splits the model into moving parts (bones), writes one animation for each state you tick, and sets each state to play it. - **What is it, and how does it move?** Optional words that steer it: *"a heavy golem that stomps and bites"*, *"hops instead of walking"*. - **Set it up too** also chooses the behaviour, health, damage, speed and experience from the description, measures the hitbox off the model, works out which way it faces and picks its head. It's on for a mob that has no animations yet. Off, your settings are left alone and it only animates. For a mob with no [abilities](#abilities) yet, it also adds the ones your words ask for: *"a boss that slams the ground and summons minions at half health"* comes back with a Ground Slam, a phase that calls minions, and an animation for each (up to two, at no extra cost). If an ability wants a VFX or sound the pack doesn't have, that step shows a button to make it, with its price. Nothing extra is generated without you pressing it. - **States to animate**: Idle, Walk, Attack, Hurt and Death are ticked to start with. Run and Spawn are there if you want them; a blank Run plays Walk. Running it again replaces the animations it wrote and keeps any others the model has. It runs in the background, so you can leave the editor and come back. ## The mob editor The model stands in the middle with its hitbox drawn round it and a blue arrow at its feet showing which way it walks. The states and sounds are on the left, everything else on the right. ### Behaviour Underneath, a mob is a vanilla mob you can't see, wearing your model. Its behaviour decides which one, and so how it moves and fights. | Behaviour | What it does | | --- | --- | | **Hostile** | Chases and hits players | | **Brute** | Big, slow, hits hard | | **Climber** | Hostile, and climbs walls | | **Ranged** | Keeps its distance and shoots | | **Neutral** | Wanders, and fights back when hit | | **Guardian** | Fights hostile mobs | | **Passive** | Wanders, and runs when hit | | **Flying** | Drifts around in the air | | **Flying hostile** | Swoops at players | | **Statue** | Never moves | **Burns in daylight** is off unless you tick it, whatever the mob walks like. **Flashes red when hurt** is on: the model goes red for a moment when it takes damage, like a vanilla mob. On servers older than 1.21.4 it shows a red outline instead. **Fire immune** stops fire and lava hurting it, and **Glowing outline** gives it the outline a spectral arrow does. A **Ranged** mob gets a **Shooting** section: what it fires (an arrow, a snowball, a small fireball, a fireball, a wither skull or a trident), the damage per hit (0 keeps the projectile's own), and how far away it shoots from. It keeps its distance like a skeleton and plays its Attack animation each time it shoots. A fireball or a skull never breaks blocks. ### Stats | Setting | What it is | | --- | --- | | **Health** | In half-hearts: 20 is ten hearts, the same as a player | | **Damage** | Per hit, in half-hearts. 0 keeps the vanilla mob's own | | **Speed** | A multiple of the vanilla mob's own speed | | **Knockback resistance** | How much of a hit's knockback it ignores | | **XP** | Experience it drops when killed | | **Notices targets from** | How far away, in blocks, it spots something to chase. Blank keeps the vanilla mob's own | ### Boss bar Turn on **Show a boss bar** for a bar across the top of the screen with the mob's name and health, shown to every player within **Seen within** blocks. Pick its colour and how many notches it has. ### Spawning Turn on **Spawns on its own** and the mob appears in the world by itself. It **takes the place of** some of the mobs the game spawns naturally rather than adding to them, so your world never holds more mobs than it would have: | Setting | What it does | | --- | --- | | **Share of natural spawns** | How many of the matching natural spawns become this mob | | **Replaces** | The vanilla mobs it stands in for. None picked is any natural spawn of its own kind: monsters for a Hostile, Brute, Climber, Ranged or Flying hostile mob, animals for a Neutral or Passive one. Guardian and Flying mobs need at least one picked | | **Biomes** | Where it spawns. None picked is every biome. Type a name with `*` in it, like `*forest*`, to match several | | **When** | Any time, only by day, or only at night | | **Light** | The light level where it appears, 0 to 15 | | **Group** | How many appear together | | **Per chunk** | Spawning stops adding more once a chunk holds this many | | **Worlds** | The world names it spawns in. None picked is every world | A mob that spawned on its own despawns when nobody is near, the way the mob it replaced would have. One you spawn with a command or an egg stays. ### Size and facing **Model size** is how big the model is drawn. **Hitbox height** is how tall the box it's hit and pushed by is, in blocks; its width grows with it. Press **Fit to model** to match it to the model at its size. The hitbox needs a 1.20.5 or newer server; older ones keep the vanilla mob's box. If the mob walks sideways or backwards, use **Turn** until the blue arrow points out of its face. **Head** picks a bone that turns to look at what the mob is after. That bone has to move in at least one animation, or it's drawn as part of the body and can't turn. ### Animations One of the model's animations per state. Press play beside a state to watch it in the editor. | State | When it plays | | --- | --- | | **Death** | Once, when it dies. The body stays until it ends (at most 5 seconds) | | **Spawn** | Once, as it appears | | **Attack** | Once, each time it hits something | | **Hurt** | Once, each time it takes damage | | **Run** | Moving fast or chasing. Blank plays Walk | | **Walk** | Moving. Blank plays Idle | | **Idle** | Standing still. Blank leaves it in its rest pose | The list is in order of importance: a mob doing several things at once plays the first one listed. The first four play once to the end unless something higher up starts; a blank one simply doesn't play. ### Sounds Ambient, hurt, death, attack and step, each a sound from the pack. Pick one, or press **+** to make a new one in the sound editor (it opens in a new tab, and the list updates when you come back). The play button beside a slot plays what it's set to. Setting any of them silences the vanilla mob underneath, so a mob with none set keeps its own sounds. Ambient plays every so often while a player is nearby. **Generate sounds with AI**, under the slots, makes the ambient, hurt, death and attack sounds for a mob that doesn't have them, such as one converted from a model. Describe the creature and tick the sounds to make. They come out short, in mono (so they're heard from the mob in game) and at matching volumes, and are saved as ordinary Sounds in the pack, each with a second take to choose from. Each take is charged like generating a Sound; the price is shown before you start. ### Abilities What it does besides walk and bite: a ground slam every few seconds, minions when it drops below half health, a poison aura, a volley of fireballs, a phase where it goes red and fast. Each ability is three things: - **When**: every few seconds, when it's hurt, when it hits something, when it appears, when it finds a target, when it dies, when a player right-clicks it or when it kills a player. Narrow it with **Health** (*Once below* 50% runs the moment it first drops under half, which is how a boss changes phase; *While below* runs every time while it's under) and conditions: only while it has a target, while its target is within or further than so many blocks, while a player is near, in or out of a phase, by day or night, in the rain, on the ground. - **Do**: steps, run in order. Play one of its animations, wait, damage, heal, knock back, pull in, leap or lunge at its target, a potion effect, set on fire, summon mobs, enter a phase, play one of the pack's VFX or sounds, particles, a chat message or a title, shoot a projectile, an explosion (it never breaks blocks), lightning, tint the model, change speed, a shield, teleport to its target. - **At whom**, per step: itself, its target, whoever set it off, players or everything within so many blocks, the nearest player, everything in front of it, or for effects a spot: where it stands, where its target stands, a spot ahead, a ring of spots, random spots near it. Plus a cooldown and a chance. **Add an ability** starts from nothing or from one of six: Ground slam, Summon minions at half health, Leap at its target, Poison aura, Fireball volley and Enrage phase. **Writing abilities as text.** The **``** button on an ability shows it as skill lines in [MythicMobs](https://mythiccraft.io) syntax, which RP Engine runs. The first line says when, every line after it is a step. Lines can use anything RP Engine supports, not only what the form offers (see [Skills](/rp-engine/skills) for the full list), and a line it can't read is pointed out as you type. Press the button again to go back to the form. Abilities need RP Engine 0.2.53 or newer. On an older version the mob walks and fights without them. ### Drops What it drops when killed, instead of the vanilla mob's loot: an item, the least and most of it, and the chance it drops at all. Search for any vanilla item, or type `studio:` for one of the pack's own items. With no drops it drops nothing but its XP. ## Spawning it in game 1. **Sync the pack**: press **Sync** and run the `/rp sync ` it shows on a server running RP Engine. That sends the pack, mobs included, to you there. For every player, serve it with [Distribution](/distribution). 2. Press **Spawn in game** on the model's page (or **Give** on its card) to get a spawn egg for it. Use the egg on a block to hatch the mob there. This needs a 1.20.5 or newer pack. 3. Or use the commands on the server: | Command | What it does | | --- | --- | | `/rp spawn studio:` | Spawns one where you stand | | `/rp egg studio: [player] [amount]` | Gives a spawn egg for it | `` is the model's id, shown on its page. Bedrock players joining through Geyser see the mob as its model too, animated the same way, from the Bedrock pack a sync sends them (RP Engine 0.2.53 or newer). See [Bedrock and Geyser](/rp-engine/bedrock#custom-mobs-and-bound-models). Entities in RP Engine What the plugin does with a custom mob, and writing one by hand in YAML. Skills in RP Engine The skill lines an ability turns into, and everything they can do. ## Exports The mob settings reach RP Engine when you sync the pack or serve it with Distribution. An exported Java `.zip` carries them too (in its `studio-content.json`), and RP Engine reads them when the zip is dropped into its `content/` folder. The other exports carry the model, but not the mob. --- Source: https://resourcepack.ai/docs/models # Models A 3D Model is an object made of cubes, each face painted with a texture: a lamp, a market stall, a statue, a car. It's the one asset type that adds a new shape rather than repainting an existing one. Players place it in the world, hold it, or wear it, and it can [animate](/animations). ![Models made in Studio: a market stall, a fire engine, a Ferris wheel, a food truck and a vending machine](/images/models.webp) ## Making one On the pack page, press **Add asset** and pick the **Model** tab. Then: - **Generate**: describe it. The AI plans the object, builds it cube by cube, paints it, and checks its own work. This takes a few minutes and costs about 75 credits; you can close the tab while it runs. See [Generating with AI](/generating) for writing a good prompt. - **Blank**: start from a template (a stone cube, a cross like a flower, a flat item, or nothing) and build it yourself. - **Upload**: bring a Blockbench `.bbmodel` or a vanilla model `.json`. See [Importing a model](#importing-a-model). Generated models look like Minecraft: a few big cubes with the detail painted onto the faces, rather than hundreds of tiny cubes. A barrel is one cube with a rim painted on it. Once you have a model, **Edit with AI** on its page changes it from a sentence ("make the roof red", "add a chimney"), and **Animate with AI** in the editor writes animations for it. Editing with AI repaints the model in the same generated style, even if you uploaded it. **Versions of one model** (a Christmas chair beside the plain one, or several textures): right-click the model on the pack page, **Duplicate**, and change the copy with **Edit with AI** or in the editor. Each copy is its own model with its own give command. To use another model's texture, see [Copying a texture](#copying-a-texture-to-another-model). Generation is a starting position The loop that gives good results: generate, look at it in game, fix the two things that are wrong, look again. ## Seeing it in game A resource pack can't add new items or blocks to Minecraft, only change how existing ones look. So every model rides on a piece of vanilla **paper**: the pack tells the game to draw that paper as your model. The item a model rides on is its **carrier**, and the Add asset sheet calls this one the **Display Entity** carrier. Placing the model in the world needs [RP Engine](/testing/plugin), our free server plugin. [Our test server](/testing/test-server) has it. 1. Press **Sync** in Studio. It sends the pack straight to you in game. 2. On the model's page, under **Get in-game**, press **Give in-game** (or copy the give command). 3. **Right-click a block** to place it. It appears on the block you clicked, facing the way you were looking. 4. **Punch it** to pick it back up. A model with an "On left click" animation can't be punched up; see [Animations](/animations). A placed model is a display entity, not a block. It doesn't fill a block space or stop water, and it stays put across server restarts. Block protection plugins don't necessarily cover it, so check that on a public server. ### Choosing what it gives The **Get in-game** card has a few options that ride on the item, so you can give different copies of one model different settings: - **Size**: from ⅛ to 8 times. The model grows from its base, so a big one stands on the block rather than sinking into it. The dropped item remembers its size. - **Plays**: shown when the model has two or more triggered animations, to pick which one this copy uses. See [Animations](/animations#triggers). ### Vehicles driving into it Under the card, **Placed behaviour** has one checkbox: **Make this model collidable with vehicles**. It's on by default. When on, vehicles stop at a placed copy of the model, tested against its actual cubes: a car can drive between the legs of a table or under an archway, and a long fence stops it along its whole length. A rotated slab works as a ramp, stairs are climbed a step at a time, and anything low enough to be a kerb is driven over. Turn it off for flat pieces a vehicle should ignore, like a rug, a manhole cover or a road marking. It doesn't affect players, who walk through placed models unless the server sets otherwise. The change reaches the server on the next Sync. It isn't shown for a model that's been converted into a [vehicle](/vehicles). ### Random turn and size Also under **Placed behaviour**, **Random variation when placed** gives every copy a player puts down a turn and a size of its own, so a field of rocks or a shelf of pots doesn't look like one model stamped out. - **Turn**: up to this many degrees either side of the way it would have faced. 180 is any direction. **In 90° steps** keeps it square to the blocks, which suits anything boxy; **any angle** suits rocks and plants. - **Size**: a range, as a multiple of its own size, such as 0.8 to 1.2. It multiplies the size chosen on the **Get in-game** card, and the dropped item keeps that chosen size rather than the random one. Each copy rolls once, when it's placed, and keeps what it rolled through restarts. Copies placed by a plugin aren't varied. It saves as you type and reaches the server on the next Sync, and needs RP Engine 0.2.57 or newer. ## The editor's five modes Click a model to open the model editor. It works like Blockbench, with five modes chosen along the top: | Mode | For | | --- | --- | | **Edit** | Building the shape: add, move, resize and rotate cubes, and group them into bones | | **Paint** | Painting straight onto the model in 3D | | **Display** | How it looks in a hand, in the inventory, on the ground, in an item frame, on a head | | **Render** | Capturing a PNG of the model on a backdrop | | **Animate** | Keyframes and when they play; see [Animations](/animations) | ## Edit mode A model is a list of **cubes** (Minecraft calls them elements). Each cube is a box with six faces, and each face shows part of a texture. Positions are in pixels, 16 to a block. A cube can sit anywhere from `-16` to `32` on each axis, with the block itself at `0` to `16`, so a model can overhang its block by a full block on every side. Keep the bulk of it near the middle so it sits well when placed. Cubes can be turned to any angle, on more than one axis. Minecraft's own format only allows a few angles on one axis, so a model with other turns needs RP Engine to show them exactly; a plain exported pack shows the nearest angle it can. ### Hotkeys Defaults, all changeable in the editor's settings: | Action | Key | | --- | --- | | Move tool | `G` | | Resize tool | `S` | | Rotate tool | `R` | | Frame selection | `F` | | Hide / show cube | `H` | | Duplicate cube | `Ctrl+D` | | Select all | `Ctrl+A` | | Copy / paste | `Ctrl+C` / `Ctrl+V` | | Delete cube | `Delete` | | Deselect | `Esc` | | Undo / redo | `Ctrl+Z` / `Ctrl+Y` | Copied cubes paste into any model, in another tab or another pack too. Any textures they use come with them. The tool rail also has a **Select** tool, for picking without a gizmo, and a **Pivot** tool, which moves the selected cube's pivot point without moving the cube. Use it when a cube turns around the wrong spot. ### Bones Select several cubes and group them into a **bone**: a named group with its own pivot point. Bones are what you animate. Turning a bone turns everything in it around one point, which is how a door swings or a wing flaps. Select a cube in a bone and the right panel shows the **Bone** card, with the bone's own pivot point and **Select members**, which selects every cube in the bone. The Move tool then moves the whole bone, its pivot going along, and the Rotate tool turns a selected bone (or several selected cubes) as one piece, around the bone's pivot (or the first cube's). Each cube keeps its own pivot, so it can still be turned on its own later. A generated model arrives already grouped, with named parts and pivots at the joints (a front wheel pivots on its axle), so it's ready to animate. Bones are saved in the same `groups` field Blockbench uses. Vanilla Minecraft ignores it, so grouping never breaks an exported pack. ### Copying a texture to another model To use one model's texture on another, select it and press `Ctrl+C`: in Paint mode, the texture you're painting; in Edit mode, pick a face in the inspector first (with only a cube selected, `Ctrl+C` copies the cube). **Copy texture** in Paint mode's right-click menu and the copy button beside a face's texture do the same. Then, in the other model (any tab, any pack), select cubes or faces and press `Ctrl+V`. With cubes selected, it goes on every face; with faces picked, only on those. A texture from another pack is copied into this one first. ### UVs Which part of a texture lands on which face is normally handled for you. The UV panel in Edit mode is there for when you need exact control. ## Paint mode Paint straight onto the model in 3D. For anything fiddlier than a quick touch-up, open the texture in the full [pixel editor](/blocks) from here; it comes back when you're done. ## Display mode Minecraft draws a held or displayed model differently in each place, and each place has its own rotation, position and scale: - **First person** and **third person**, in each hand - **On a head** - **On the ground**, as a dropped item - **Item frame** - **Shelf** - **GUI**, the inventory icon Slots you leave alone use the vanilla defaults, so only change the ones that look wrong. The preview has a player (Steve, Alex or your own skin) so you can judge a held model against a body. Take care over the GUI slot. The inventory icon is how players find your model at all. **Model scale**, also in the editor, resizes the model itself, so every copy is that size in the exported pack too. ## Render mode The same viewport set up for screenshots. Pick a backdrop (Transparent, solid colours including a green screen, gradients, or a Minecraft sky and grass), frame or spin the model, and capture a PNG. A transparent backdrop gives a PNG with a real transparent background, ready for a Discord post or a store listing. ## Importing a model Two formats upload: - **`.bbmodel`** (Blockbench) keeps its cube names, its groups (as bones), its animations, its textures and its rotations, so a rigged Blockbench model arrives ready to animate. - **`.json`** (a vanilla block model) comes in as geometry. A `.json` only names its textures and doesn't carry them, so drop the PNGs in with it: each one is matched to the texture of the same file name. The model's row lists every texture it names with its file, or **missing**: **Add texture** fills a missing one, and **Replace texture** swaps one you already added. **"Model has no valid geometry"** means the file has no cubes in it. A vanilla flat item model such as `wheat_seeds.json` (`"parent": "item/generated"`) only names a texture: it is a picture, not a 3D shape. Reskin that item as an [Item](/items) with its PNG instead. A model too big for Minecraft's model box is scaled down to fit. Cubes only. Minecraft's model format has no meshes, so mesh geometry in a Blockbench file doesn't come across. ## What's in the exported pack A model is exported as a JSON file in Minecraft's block-model format, with its textures beside it. An item definition for paper points at it, so paper with the right item data draws as your model. The give command on the model's page produces that item. Animations need RP Engine Keyframes and bones are saved in fields vanilla ignores. The pack is still valid, but the model stands still unless RP Engine is playing it. See [Animations](/animations). ## On Bedrock Models convert to Bedrock. The `.mcpack` carries each model as a Bedrock entity, with your animations as native Bedrock animations, and cube rotations come across exactly. Something still has to put that entity in the world. On a server that's [RP Engine](/rp-engine/bedrock), which draws placed models for Bedrock players near them. Without it, a model is its item: Bedrock players hold it with the model's icon, given by the same command, if the server has the [Geyser export](/bedrock#without-rp-engine). A `.mcpack` in a Bedrock world on its own has the models defined but nothing to place them. --- Source: https://resourcepack.ai/docs/moving-assets # Moving assets between packs You can copy or move anything you've made into another pack, one asset at a time or many at once, without generating it again. **Copy** leaves the original where it is. **Move** takes it out of this pack. ## Copying or moving Choose what to send For **one asset**, press **Move to pack** on its page, or right-click it in the pack grid. For **several**, tick them in the grid (the checkbox appears top-left when you hover a card) and press **Move to pack** in the bar that comes up. **Select all** ticks everything on the tab you're on. Pick the pack Choose an existing pack, or type a name to make a **new** one on the spot. Choose Move or Copy Then confirm. ## What changes on the way Most assets arrive exactly as they were. A few details are given out once per pack, so they're reassigned in the new one: | What | What happens | | --- | --- | | A model's **carrier** (the vanilla item or block the game draws as your model) | Reassigned in the new pack. Same kind where one is free, otherwise the item carrier | | A GUI overlay's **characters** | New ones, so the title text that opens the GUI changes. Copy it again from the GUI's page | | An icon's **character** | Kept, unless another icon in the target pack already uses it | | The textures a model **uses** | Copied along with it, so it doesn't arrive as a black-and-magenta checkerboard | Reskins can't sit side by side A block or item reskin is named after the vanilla thing it replaces, so a pack can only hold one of each. If the target already has that block reskinned, yours is left behind and you're told so. Tick **Overwrite** in the sheet if you meant to replace it. --- Source: https://resourcepack.ai/docs/own-key # Bring your own key Add your own OpenAI key, and **3D models (generating, editing and animating them) bill to your OpenAI account instead of your AI Credits**. Everything else still uses AI Credits. It's on every paid plan. Starter doesn't include it. ## Set it up 1. Make an API key in your OpenAI account. 2. In Studio, open **Account** and find **Bring Your Own Key (BYOK)**. 3. Paste the key and save it. 4. Optionally, pick the **Orchestrator model** that runs on it, to balance price against quality. From then on, 3D model actions cost 0 AI Credits and show up on your OpenAI bill instead. To go back to AI Credits, remove the key. For a Team, an admin sets the key in the Team's settings. One key covers the whole Team, and Team packs always use the Team's key, never a member's own. See [Teams](/teams). ## What your key actually pays for Your key runs the **orchestration layer**: the language model that plans a 3D model, decides what to build and checks the result. That's the only part of the work that runs on a standard provider, so it's the only part a key can cover. The rest is ours. Every model goes through our own proprietary build pipeline, which we run and pay for ourselves whether or not you bring a key. So a key doesn't make a model free to make: we still carry most of the cost, and the key takes over the part that can be handed over. ## Why only 3D models Blocks, items, icons, GUIs and the rest of the picture work come from our own image models. There's no orchestration step on a standard provider there, only proprietary models we built and host, so there's no key that could stand in for them. We'd like to offer the same for pictures, and if that changes, it will be listed here. ## Your key is safe with us Your key is encrypted before it's stored, and it's only read at the moment a 3D model action runs on it. If a key stops working (revoked, out of funds, or your plan ends), Studio stops using it and those actions go back to AI Credits. If your plan ends, a key you stored is kept but isn't used until you're on a paid plan again. --- Source: https://resourcepack.ai/docs/packs # Packs A pack is one project: everything for one server or one look. It becomes one resource pack in Minecraft. Each thing in it (one Block texture, one 3D Model, one Sound) is an **asset**. You test, share and export a whole pack at once. The pack page has a tab for each kind of asset: Models, Vehicles, Mobs, Blocks, Items, Armor, GUIs, HUD, Dialogs, Icons, Sounds, Emotes and Shaders. 2D and 3D Items share Items, 2D and 3D Armor share Armor, Rank Tags sit under Icons, and Text Effects and VFX under Shaders. ## Making a pack Press **New pack** on the dashboard. Studio suggests a name and an icon; use the dice to pick others, or upload your own image. Both can be changed any time. Already have a resource pack as a `.zip`? Press [Import](/importing) beside it instead, which makes a new pack from the file. ## Copying, renaming and deleting Right-click a pack card (or open its menu) for **Open pack**, **Edit pack**, **Duplicate**, **Export**, **Change icon** and **Delete pack**. Duplicate copies the whole pack, assets and all, so you can experiment without risking the original. **Edit pack** changes the name and description. It also has one setting that matters once you've invited other people: whose AI Credits they spend when they generate. See [Collaborators](/collaborators#whose-credits-get-spent). ## Sorting a pack into folders Folders keep a big pack tidy. They're listed beside the grid like folders in a file manager (on a narrower screen, as a row above the tabs). Click one and the grid shows what's in it; click the pack's name above them to see everything again. Each folder holds one kind of asset: a folder of models, a folder of icons, a folder of emotes. The **+** beside the list's title makes one, asking for a name, what it holds and a colour. Click the title itself to choose what the list shows: every folder **A–Z**, or only the folders of one kind. The button beside the **+** tucks the list away to a small **Folders** tab, and it stays tucked away until you open it again. **Show folders**, with the pack's buttons at the top, decides how the grid treats them. On (the default), folders also appear as tiles at the top of the pack, and whatever is filed in one is tucked inside it rather than shown in the grid; hover a tile to see the first few things inside. Off, every asset stays in the grid where it always was, with a small folder mark on anything filed, and the folder list is how you narrow it down. The setting is remembered. To put things in a folder: - **Drag** a card onto it, in the folder list or onto its tile. Drag a card you've ticked and the whole selection comes with it. - **Tick several** and use **Move to folder** in the bar that comes up. The same menu can make a new folder for them on the spot. - **Right-click** a card and choose **Move to folder…** To take something out, drag it onto the pack's name in the folder list, or use **Move to folder → Take out of folder**. Searching from the top of the pack looks inside every folder, and each result shows which folder it's in. Folders only change how the pack page is laid out, never what the pack exports or what reaches a server. Deleting a folder puts everything in it back at the top of the pack rather than deleting it. Folders are one level deep, and an asset is in at most one. ## Saving Everything saves as you go; there's no save button and no build step. **Sync** (which sends the pack to your game, see the [Quickstart](/quickstart)) and [Export](/exporting) always use what's in the pack right now. ## Which Minecraft versions it works on You don't set this. Studio works it out from what's in the pack, and the pack card shows the oldest version that will load it, for example "1.21.4+". A pack with nothing special in it works on **1.19.4** and newer. Some assets need a newer game: | Asset | Needs | | --- | --- | | A reskin of a block or item added in a later update (pale oak, say) | The update that added it | | An Item variant (a second look for an item, handed out by command) | 1.21.4+ | | A 3D Model with glowing parts (light emission) | 1.21.3+ | | A 3D Model with its own position for shelves | 1.21.9+ | | A Dialog | 1.21.6+ | Each asset shows its own minimum as a chip on its page, with the reason; for a model, it names the cubes responsible. Delete or change that asset and the pack works on older versions again. ## How many packs you can have | Plan | Packs | Assets per pack | | --- | --- | --- | | Starter | 5 | 50 | | Hobby | 20 | Unlimited | | Creator | 20 | Unlimited | | Studio | 20 | Unlimited | | Team | 50 | Unlimited | --- Source: https://resourcepack.ai/docs/plugins # Plugins Besides [RP Engine](/rp-engine), we make a few server plugins that each do one thing. None of them needs RP Engine installed, and none needs a ResourcePack AI account. Two are addons: they need another plugin here to run, and say so. MC GUI Web pages in the game: menus and shops in HTML and CSS, fullscreen with a mouse pointer or on walls. Dialog Engine Minecraft's own dialog menus, written in YAML: buttons, text boxes and sliders, with a Java API. Punishments Warn, mute, kick and ban from a menu or plain commands. Uses Dialog Engine for the menu. 3D Engine Real 3D models: drop in a .glb, .gltf or .obj file and place it in the world. 3D Pets A 3D dog that follows you and plays fetch. Needs 3D Engine. ## What each one runs on | Plugin | Server | Minecraft | Needs | | --- | --- | --- | --- | | [MC GUI](/mcgui) | Spigot, Paper or Folia | 1.21.11 and newer | Nothing else | | [Dialog Engine](/dialog-engine) | Spigot or Paper | 1.21.7 and newer | Nothing else | | [Punishments](/punishments) | Spigot or Paper | 1.21.7 and newer | Dialog Engine, for the menu | | [3D Engine](/3d-engine) | Spigot or Paper | 26.3 | Nothing else | | [3D Pets](/3d-pets) | Spigot or Paper | 26.3 | 3D Engine | Players install nothing for any of them. Where a plugin needs a resource pack, it builds that pack and sends it to players itself. ## Which plugin for menus Minecraft has three kinds of menu screen, and we make something for each. They are separate: a menu made for one doesn't open in another. | You want | Use | What players see | | --- | --- | --- | | A restyled chest, furnace or anvil, with items players can pick up and move | A [GUI](/guis) designed in Studio, opened by [RP Engine](/rp-engine/screens) or by any menu plugin that uses its title | The game's own container screen, with your art drawn over it | | A menu of buttons, text boxes, toggles and sliders that opens instantly | A dialog, in [Dialog Engine](/dialog-engine) or [RP Engine](/rp-engine/dialogs) (Minecraft 1.21.6+). Studio can [design one](/dialogs) for either | The game's own dialog screen. A plain dialog needs no resource pack; one drawn in Studio comes with a small one | | A full page with a mouse pointer, laid out however you like, or a screen on a wall | [MC GUI](/mcgui) | A web page rendered into the game. The player sits while it is open | **Dialog Engine or RP Engine for dialogs?** Both open the same kind of screen, but they don't share or sync dialogs: each opens its own (`/de open` and `/rp dialog`). If you already run RP Engine, use its dialogs. If dialogs are all you need, or your own plugin needs to hear button presses (`DialogClickEvent`), use Dialog Engine. A dialog drawn in Studio can be exported for either. --- Source: https://resourcepack.ai/docs/punishments # Punishments An **addon** for [Dialog Engine](/dialog-engine): a separate plugin that uses Dialog Engine to draw its screens. Unlike most addons it also works without it, as plain commands. It is a punishment plugin whose staff tools are a real Minecraft menu. `/punish Steve` shows Steve's record and a button for each of warn, mute, kick, temp-ban and ban, and every button does exactly what the matching command does. ![The punishment panel, picking a reason](https://resourcepack.ai/listings/punishments/panel.png) ## Installing Install Dialog Engine for the panel The panel is drawn by [Dialog Engine](/dialog-engine) **0.4.1 or newer** (free). Without it, Punishments still works: every command does, only `/punish` and the screens need Dialog Engine. Drop it in [Download Punishments.jar](https://cdn.resourcepack.ai/Punishments.jar), or get it from [SpigotMC](https://www.spigotmc.org/resources/139570/), and put it in `plugins/`. Then start the server. Open the panel Its screens install themselves into Dialog Engine on the first start, in `plugins/DialogEngine/drawn/punishments/`. Type `/punish` and a player's name. It runs on **Spigot or Paper 1.21.7 and newer**, one jar for both. The panel needs players on **1.21.6 or newer** (1.21.9 or newer to see players' heads). Players install nothing: Dialog Engine sends the panel's small resource pack the first time somebody opens it. ## The panel `/punish ` opens it. `/punish` on its own lists who is online, and takes a typed name for anybody who is not. - **Reason, Length and Silent** are remembered per staff member, so they stay where you left them. - **Length "Auto"** uses the length set for the chosen reason in `config.yml`. - **Unmute and Unban** appear only when they apply. - **Temp-ban and Ban ask first**, with a box for details that are added to the reason. - **History** lists everything the player has had, each with a Revoke button. - **Every button checks the same permission as its command** when it is pressed: a helper without `punishments.ban` cannot ban from the panel either. A warned player sees a popup they have to acknowledge. If they were offline, they see it the next time they join. ## Commands | Command | What it does | Permission | |---|---|---| | `/punish [player]` | The panel | `punishments.punish` | | `/warn [-s] [reason]` | Warn | `punishments.warn` | | `/unwarn ` | Remove the newest warning | `punishments.unwarn` | | `/mute [length] [-s] [reason]` | Mute | `punishments.mute` | | `/unmute ` | Unmute | `punishments.unmute` | | `/kick [-s] [reason]` | Kick | `punishments.kick` | | `/tempban [-s] [-ip] [reason]` | Temp-ban | `punishments.tempban` | | `/ban [length] [-s] [-ip] [reason]` | Ban, for good unless a length is given | `punishments.ban` | | `/unban ` | Unban | `punishments.unban` | | `/history ` | Their record | `punishments.history` | | `/punishments reload` | Read `config.yml` and `messages.yml` again | `punishments.admin` | | `/punishments revoke ` | Lift one punishment by its number | `punishments.revoke` | - **Lengths**: `30m`, `2h`, `7d`, `2w`, `1mo`, `1y`, combined like `1d12h`, or `perm`. Leave it out and the reason's own length is used. - **Reasons**: a reason starting with `#` is a preset from `config.yml`, and anything after it is details: `/tempban Steve #hacking flying at spawn`. - **`-s`** is silent: only staff with `punishments.notify` hear about it. - **`-ip`** also bans the player's address. A local or private address (loopback, `10.x`, `192.168.x` and the like) is refused, because behind a proxy or on a LAN it is everybody's. - Everything but kick works on offline players. Every command's name and aliases are in `config.yml`, and any command can be turned off there. Punishments takes `/ban`, `/kick` and the rest over from vanilla and other plugins. ## Permissions Every command and option has its own node, so you can hand out exactly the ones a rank needs. All are op-only by default, except the last two. | Node | Allows | |---|---| | `punishments.punish` | `/punish`, the panel | | `punishments.warn`, `.unwarn` | `/warn`, `/unwarn` | | `punishments.mute`, `.unmute` | `/mute`, `/unmute` | | `punishments.kick` | `/kick` | | `punishments.tempban` | `/tempban` | | `punishments.ban` | `/ban`, permanent or with a length | | `punishments.ban.ip` | `-ip` on a ban | | `punishments.unban` | `/unban` | | `punishments.history` | `/history` | | `punishments.revoke` | `/punishments revoke`, and Revoke in the history | | `punishments.notify` | Hearing silent punishments and staff-only announcements | | `punishments.update` | Being told on joining that a newer version is out | | `punishments.staff` | All of the above except `punishments.update` | | `punishments.admin` | `/punishments reload`, and everything in `punishments.staff` | | `punishments.exempt` | Cannot be punished by players. Off by default | | `punishments.limit.helper`, `.limit.moderator` | The caps under `limits:` in `config.yml`. Off by default | An offline player counts as exempt if they held `punishments.exempt` when they were last online. ## Setting it up `plugins/Punishments/config.yml`: - **`storage`**: SQLite out of the box, or MySQL/MariaDB to share one record across a network. Changing it needs a restart. - **`reasons`**: the presets, each with how long a mute and a temp-ban for it last. - **`limits`**: caps per staff rank, by permission. A helper might mute for a day and temp-ban for three; longer lengths are cut down, and the staff member is told. - **`warnings`**: when warnings stop counting, the popup, and **escalation**: three warnings runs a mute, five a temp-ban, or whatever commands you write. A step only runs if the warner could have run that command themselves. - **`mute`**: which commands a muted player cannot use, and whether signs and books are blocked too. - **`broadcast`**: who hears about each punishment: everyone, staff or nobody. - **`update-check`**: whether to ask SpigotMC for newer versions. `plugins/Punishments/messages.yml` has every word, in [MiniMessage](https://docs.advntr.dev/minimessage/format.html), including the kick and ban screens and everything written on the panels. `/punishments reload` reads both. ## Changing the screens The screens are ordinary Dialog Engine drawn dialogs, so they open in its browser editor: `/de edit punishments:panel`, or `confirm`, `history`, `players` and `warned`. **A screen you have edited is kept** when Punishments updates; delete its folder in `plugins/DialogEngine/drawn/punishments/` to take the new version's. ## For developers Add `depend: [Punishments]` to your `plugin.yml` (or `softdepend`, and check `Punishments.isEnabled()` first) and compile against the jar. The API is in `ai.resourcepack.punishments.api`. Needs Punishments 0.1.3 or newer. ```java PunishmentsAPI punishments = Punishments.api(); // Online and muted? Answers at once, for a chat plugin. if (punishments.isMuted(player)) return; // Anybody, online or not. Futures complete on the main thread. punishments.activeBan(uuid).thenAccept(ban -> ban.ifPresent(b -> sender.sendMessage("Banned for: " + b.reason()))); punishments.history(uuid, 20).thenAccept(rows -> rows.forEach(this::show)); punishments.warnings(uuid).thenAccept(count -> { /* the number escalation counts */ }); // Punish and lift, as if the actor had typed the command. null is the console. long hour = 60 * 60 * 1000L; punishments.punish(null, Punishment.Type.MUTE, "Steve", "Spamming", hour, false); punishments.punish(null, Punishment.Type.BAN, "Steve", "#hacking", Punishment.NEVER, true); punishments.revoke(null, Punishment.Type.MUTE, "Steve"); ``` - `mute(player)` and `isMuted(player)` are for online players and answer from memory. Everything else reads the database and returns a `CompletableFuture`. - `punish` goes through everything the command does: reason presets (`#hacking`), the actor's limits, exemptions, the events below, the broadcast and escalation. The actor is told the outcome in chat. Only the command's own permission is skipped, because your plugin has already decided. - The length is in milliseconds. `Punishment.NEVER` is for ever, and `0` is the default from `config.yml`. A warning and a kick ignore it. - A `Punishment` says what it is: `type()`, `reason()`, `actorName()`, `created()`, `expires()`, `permanent()` and `inForce(now)`. Three Bukkit events, all on the main thread, in `ai.resourcepack.punishments.api.event`: | Event | | |---|---| | `PunishmentPreEvent` | A punishment is about to be given. Cancellable, and the reason can be changed | | `PunishmentEvent` | A punishment was given | | `PunishmentRevokeEvent` | A punishment was lifted | --- Source: https://resourcepack.ai/docs/quickstart # Quickstart This page takes you round the whole loop once: make a pack, generate a new stone texture into it, and walk up to it in Minecraft. It takes about five minutes. You'll need A free ResourcePack AI account, and Minecraft: **Java or Bedrock**. You don't need to install anything. Generating uses **AI Credits**, the app's currency: a free account gets 50 every month, and a Block costs 10. ## Make something Create a pack Open [studio.resourcepack.ai](https://studio.resourcepack.ai) and press **New pack**. Give it a name; the description and icon are optional. A pack holds everything you make, and it's what you test and export. Press Add asset Each thing in a pack is an **asset**. The sheet that opens has a row of tabs across the top for **what** you're making: Model, Block, Item, Armor, GUI, Dialog, HUD, Icon, Sound, Emote, Shader, Text Effect and VFX. Under them you choose **how** to start: | Option | What it does | | --- | --- | | **Generate** | You describe it and the AI makes it | | **Blank** | Opens the editor with nothing in it | | **Upload** | Uses files you already have | Pick the **Block** tab and **Generate**. Describe what you want Choose the vanilla block to replace (say, **Stone**), then describe the new look in a sentence. Every Stone block in the game will wear it, so you'll see it everywhere you dig. Talk about the material and its wear, not about pixels: > rough grey granite, hairline cracks, small flecks of white quartz The cost is shown next to the **Generate** button before you press it. A Block takes a minute or two. A 3D Model takes a few minutes, and you can leave the tab while it works. See [Generating with AI](/generating) for every type and what it costs. Edit it What comes back is a starting point, not the finished thing. Click it to open its editor and fix what isn't right. Blocks, Items and Icons open in the [pixel editor](/blocks), and 3D Models in the [model editor](/models). ## See it in Minecraft The quickest way is our test server. It already runs everything a pack needs. Join the test server In Minecraft, add the server and join, from Java or Bedrock. Go through the portal in the lobby for a private world of your own, which is kept between visits. Link your account (once) In Studio, open your account page. Under **Minecraft account**, press **Get link code**, then type the command it shows in game: ``` /permlink 48213097 ``` You only do this once. It tells Studio which Minecraft player is you, so it knows where to send your pack. Press Sync Back in Studio, press **Sync** at the top of the pack page. Sync sends the pack to your game, to you alone: other players don't see it. On Java the new stone appears where you're standing in a few seconds. On Bedrock you're disconnected and reconnected for a few seconds, because Bedrock only accepts a pack while joining. Go round again Change something in Studio, press Sync, look again. Good packs come from going round this loop a lot, not from getting it right first time. Your own server To test on your own Paper or Spigot server instead, install our plugin, [RP Engine](/testing/plugin). Sync works there the same way. ## When it's finished: export it You never need a file to test. When the pack is done, export it as a Java `.zip` or a Bedrock `.mcpack` from the pack page. To use the `.zip` in your own game, put it in your `resourcepacks` folder: ```bash # Windows %APPDATA%\.minecraft\resourcepacks # macOS ~/Library/Application Support/minecraft/resourcepacks # Linux ~/.minecraft/resourcepacks ``` Then turn it on under **Options → Resource Packs**. The exported pack doesn't depend on us and keeps working if you never open Studio again. The exceptions are things vanilla Minecraft can't do on its own, such as animated models, Vehicles and Emotes, which need RP Engine on the server. See [Exporting a pack](/exporting). --- Source: https://resourcepack.ai/docs/rank-tags # Rank Tags A Rank Tag is the badge in front of a player's name: a rounded red **OWNER**, a gold **VIP** with a crown, a blue **MOD** with a shine sweeping across it. You make it in Studio and use it as a LuckPerms prefix or suffix (or the prefix of any other permissions plugin). ![Animated rank tags made in Studio](/images/rank-tags.gif) In your resource pack a Rank Tag is an [Icon](/icons): a single text character that draws as the picture. Unlike an Icon you never paint it. It's built from parts (a shape, a surface, a frame, the words, an icon, an animation) and you change it by changing those. ## Making one Open a pack, press **Add asset**, pick **Icon** and set **Type** to **Rank Tag**. Then either: - **Generate**: name the rank and a colour. It costs 5 credits and takes a few seconds. One rank comes back as **three takes** to choose from. Name several ranks (`VIP, MVP and MVP+`) and you get a **matching set**, one tag each, for the same price. - **Blank**: type the words, pick a colour and a look. Either way it opens in the editor. A colour in the prompt is the **background**, unless you say it belongs to the letters or the outline: | Prompt | What you get | | --- | --- | | `a red OWNER tag` | A red tag, white letters | | `an ADMIN tag with red text` | Red letters on a dark tag | | `a gold VIP+ tag with a white plus` | A gold tag, the `+` in white | | `a glossy BUILDER tag with a hammer` | A shiny tag with a hammer in a cell | | `an OWNER tag with a shine` | A tag with a shine sweeping across it | | `VIP, MVP and MVP+ tags` | A set of three that belong together | With no colour you get the one servers usually give that rank: red for owner, blue for moderator, gold for VIP and so on. ## Putting it on a rank 1. On the tag's page, type the LuckPerms group, pick **Prefix** or **Suffix**, and copy the command it writes: ``` /lp group owner meta setprefix 100 "&f " ``` `` stands for the tag's own character, which the page fills in. You can't type it by hand, so always copy the command. 2. Run it in the console or in chat. 3. Make sure players have your pack: put it on your server with [Distribution](/distribution), or [export it](/exporting) and serve it yourself. Without the pack the tag shows as a blank box. Any chat, tab-list or nametag plugin that shows LuckPerms prefixes then shows the tag, because it's just a character in the prefix. - **Keep the `&f`.** The game tints a character with the colour of the text it's in, so a tag after `&c` comes out red. White leaves its colours alone. - **An animated tag uses a hex colour instead of `&f`**, like `&#fcfcf4`. That exact colour is what makes it play, so keep it. If your chat plugin writes hex another way, use the same six digits in its spelling (`<#fcfcf4>`, `{#fcfcf4}`). Keep the `&r` after the tag too, or many chat plugins draw the player's name in that colour and it shimmers along with the tag. - **Priority** (the `100`) decides which prefix wins when a player is in several groups. Give higher ranks higher numbers. The soft dark copy one pixel down and right of the tag in chat is the game's ordinary text shadow, not part of your tag. ## The editor The tag sits large in the middle, drawn the way the game draws it and playing if it's animated. Under it, **Where it shows** draws it at game size in **Chat**, the **Tab list**, the **Scoreboard** and **Above head**. Switch these between prefix and suffix, or change the player name shown. The panel on the right holds the tag's parts. Click a section heading to fold it away. | Section | What it sets | | --- | --- | | **Text** | The words, the **Font**, the letter **Colour**, the **Effect** (Shadow, Drop, Outline, Outline + shadow or None) and its colour, and a separate colour for the `+` in VIP+ | | **Background** | The **Shape** (Square, Rounded, Pill, Chamfer, Ribbon, Slant or Arrow), the **Surface** (Flat, Gradient, Gloss, Panel, Stripes, Dither, Sparkle, or **Block**: a real block texture tinted toward the tag's colour) and the **Fill** colour. Block offers iron, gold, diamond and emerald, and the **+** opens every block in the game | | **Frame** | The **Outline** (automatic, your own colour, or none), an **Inner rim**, a **3D edge** that stands the tag up off the line, and the **Padding** round the words | | **Icon** | Over a hundred built-in icons, or one of your pack's own [Icons](/icons) under **This pack**, placed **In a cell**, **Beside** the words or on a **Tile** of its own. If you redraw a pack icon later, the section offers **Use the new one** | | **Motion** | None, **Glint** (a shine sweeps across), **Rainbow** (the letters cycle colours), **Twinkle** (sparkles come and go), **Pulse** (the frame breathes), or **Custom**: your own, on a timeline (see [Your own animation](#your-own-animation)). Point at one to preview it. **Animate with AI** under them makes a custom one from a sentence | | **In game** | **Size**, from a quarter to 4x, and **Height**, to sit it higher or lower on the line | Click any colour swatch for the picker. A **+** beside the letter colour fades the words to a second colour; one beside the fill makes a gradient of up to three. Colours you don't set follow the background (the outline, the shadow and the icon's cell are darker shades of it) until you set them yourself. **Looks**, at the bottom of the panel, restyles the whole tag in one click and keeps the words, colour and icon: Classic, Rounded, Pill, Button, Panel, Frame, Chamfer, Ribbon, Slant, Stripes, Gold block and Obsidian. **Fonts.** **Block** is chunky 5-pixel capitals, the classic rank look, one line of chat tall. **MC** is the game's own font in any case (Sr.Mod, Builder), and **Bold** is that font in bold. **Own** uses a TrueType (`.ttf`) font you upload to the pack. Block and MC have English letters only. For a tag in Thai, Chinese, Japanese, Russian or another alphabet, upload a font that has those letters under **Own**. If the pack already has one, typing the words switches the tag to it. See [Your own fonts](/dialogs#your-own-fonts) for file types and sizes. **Edit with AI**, in the top bar, changes the tag from a sentence ("make it gold", "add a crown", "make it shine", "half the size") for 5 credits. The change arrives as an unsaved edit: keep it with **Save** or undo it. **Save** keeps the tag's character, so a prefix already using it shows the new look at once. Ctrl + Z undoes and Ctrl + S saves. ### Keeping it to one line of chat A Block tag with an outline is 9 pixels tall, exactly one line of chat, so it never overlaps the lines around it. A letter outline, a 3D edge, the MC font and bigger sizes make it taller: save those for the scoreboard, the tab list and holograms. **Sizes.** 1x, 2x, 3x and 4x are pixel for pixel. Smaller than 1x is smaller than chat's own letters: a ½x tag keeps every pixel at GUI scale 2 and up, a ¼x tag only at GUI scale 4. In-between sizes are scaled by the game, so a few pixels come out a little wider than others. The chat line under the preview shows it as the game will. ### Painting on it by hand **Paint by hand**, beside Looks, turns the tag into a plain Icon with the same picture and the same character, which the pixel editor can open. After that its parts are no longer editable, an animated tag keeps only its first frame, and a tag at an in-between size becomes the next whole size up. ## Animated tags An animated tag plays in chat, the tab list, the scoreboard, and anywhere a menu or the HUD draws text. A built-in animation loops sixteen frames at ten a second, as the editor plays it. The animation is played by a text shader that comes inside your pack, so players need the pack and the command's colour (see above). Over a player's head it shows its first frame. ## Your own animation Pick **Custom** under **Motion** and a timeline opens under the tag, like the one in the model editor's Animate mode. It starts from the animation the tag had, so a Glint becomes a shine you can change. Each row is a **track**: one effect on one part of the tag. | Effect | What it does | Its value | | --- | --- | --- | | **Tint** | Washes the part toward a colour: white to flash, black to dim, red to burn | How far, 0 to 100% | | **Hue** | Turns the colours round the colour wheel. **Spread** turns each column a little more, which makes a rainbow across. White, black and greys have no hue to turn, so tint white words first (Start from Rainbow does) | How far, 0 to 360° | | **Shine** | A diagonal band of light with soft edges, as wide as you set | Where the band is, 0% (before the tag) to 100% (past it) | | **Sparkle** | Stars, somewhere new every frame | How many | | **Wave** | Bands of light running along the tag, as long and as fast as you set (a negative speed runs them backwards) | How bright, 0 to 100% | | **Particles** | Small things that fall, rise, drift or twinkle: rain, snow, embers, hearts. See [Particles](#particles) | About how many are on the tag at once | | **Paint** | Frames you paint yourself, pixel by pixel. See [Painting frames](#painting-frames) | How strongly the paint shows, 0 to 100% | A track lights the **Whole tag**, **Behind the words** (the whole tag except its letters), the **Face**, the **Words**, the **Frame** (outline and rim), the **Icon cell** or the **Icon**. Tint, Hue, Shine, Sparkle and Wave never touch the outline and shadow of the words, so the words stay readable whatever the face is doing. Tracks run top to bottom, each on what the one above left. The diamonds are **keyframes**. Each sits at a frame and at a height, which is its value: drag one sideways to move it in time and up or down to change it, or pick it and set its value exactly under the timeline. Double-click a row for a new one, and Delete takes the picked one away. **To the next key** says how a key travels to the next: **Linear**, **Smooth** (eases in and out) or **Hold** (stays put, then jumps). The line through the diamonds is what the game plays. The keys loop: after the last one the value travels back to the first, so a loop that starts and ends on the same value never jumps. For a shine that crosses and starts again, put a key at 0% on the first frame and one at 100% on the last. Above the rows: **Frames** is one loop's length (4 to 48; changing it stretches the keys to fit), and **5, 10 or 20 fps** is how fast it plays. Space plays and pauses, the arrow keys step a frame, and clicking the ruler jumps there. **+ Track** adds one (up to six), the eye mutes one without losing it, and **Start from** replaces the timeline with one of the built-in animations to build on. ### Particles A Particles track puts small moving things on the tag. Pick the track and its settings open under the timeline. **Start from** fills them all in for Rain, Snow, Embers, Fire, Bubbles, Stars, Confetti, Hearts, Code rain or a Shooting star, and every one of them is then yours to change: | Setting | What it does | | --- | --- | | **Colours** | Up to three. **Solid** is how much of a colour is laid on: lower it for glassy rain. With more than one colour, each particle is one of them, or goes through them all as it ages (a flame: pale yellow, then orange, then red) | | **Shape** | Dot, Glow, Plus, Square, Dash, Ring, Flake or Heart, or **Your own**: a five by five grid where a click makes a pixel solid, a second click soft, a third clears it | | **Across** and **Down** | How far it moves each frame. Down below zero rises. Both at none, it stays put and twinkles | | **Trail** | Pixels fading behind it: two or three for rain, five for a shooting star | | **Lasts** | How many frames each one lives. At zero it crosses the whole tag. A short life with a rising particle makes flames that die out part way up | | **Fades** | In, out, both or not at all | | **Wanders** | How far it drifts side to side as it goes: snow, embers, bubbles | | **Speeds differ** | At zero they all move alike, which looks mechanical; 40% looks natural | | **Appears** | **At the edge** it comes in from, or **Anywhere** on the tag | | **Shuffle** | Another arrangement of the same particles | Its keyframes are how many there are, so a storm can build and ease. Particles on **Behind the words** pass over the face, the frame and the letters' outline and never over the letters, which is what keeps a tag readable in the rain. ### Painting frames A Paint track is drawn by hand. Pick it and the tag above the timeline takes the brush: drag on it to paint the frame the playhead is on, and use the right mouse button (or the **Eraser**) to take paint off. The arrow keys step a frame at a time, and a mark under the track shows which frames have paint. Its **Palette** holds up to fifteen colours, each with its own **Solid**. Under **Frame**, **Last frame** copies the paint of the frame before, **Every frame** puts this frame's paint on all of them, **Clear** takes it off, and the arrows under **Move it** nudge it a pixel at a time, so a moving thing is a copy and a nudge per frame. Its keyframes are how strongly the paint shows, which lets painted frames fade in and out. Paint lies only on pixels the tag has (it cannot go outside the tag's shape) and only on the part the track is **On**. ### How much a tag can hold Painted frames and particles are stored inside the tag's own picture, and a tag only has so much room for them: the smaller and narrower the tag, the more. **Paint** beside **Start from** shows how much is taken. Past 100% the tag won't save. To get room back, paint fewer frames or use fewer colours, turn the particles down or shorten their trails, make the loop shorter, or make the tag narrower or smaller under **In game**. ### Animate with AI **Animate with AI**, on the timeline or under **Motion**, writes the timeline from a sentence: "rain falling behind the words", "embers rising off the bottom", "a slow gold shimmer", "flash white every second", "rainbow letters with sparkles on the face", "the frame burns like lava". Name a thing and it puts that thing on the tag, with particles or painted frames where it needs them. It looks at your tag first, then plays what it wrote frame by frame and fixes what it sees before you get it: rain you cannot see, a shine too faint to notice, words that get hard to read, a loop that jumps where it starts again. A new animation comes in three versions, playing side by side under **Versions**. The first lands on the tracks, and clicking another swaps it in. Once your tag plays an animation of its own, you choose between **Change this one** (one version, changed as asked) and **New ideas** (three new versions). New ideas cost more than a change; the price is beside the button. Whatever lands is an unsaved edit, like Edit with AI: **Save** keeps it and undo takes it back. The versions stay in the popover until you leave the editor. A custom animation plays in game the same way the built-in ones do, in its own colour, which the tag's page puts in the command. A pack can hold sixteen tags with their own animation. If you run your pack through an image optimiser, tell it to leave font textures exactly as they are (no colour reduction, and no changes to transparent pixels): an animated tag keeps what it needs in them. RP Engine's PackSquash setup already does. ## Sharing it **Publish to Gallery** on the tag's page puts it in the [Gallery](https://resourcepack.ai/gallery). Anybody can add it to a pack of their own and edit it like any other tag. A tag in one of your own fonts takes the font with it. ## In a content folder [RP Engine](/rp-engine) can draw the same tags from a few lines of YAML in its content folder (the folder of files on your server it builds a pack from). See [RP Engine rank tags](/rp-engine/rank-tags). ## Exporting A Rank Tag exports as an Icon does: its PNG under `assets/minecraft/textures/font/` and its entry in `assets/minecraft/font/default.json`. An animated tag's PNG is its first frame, and the text shader that plays it goes in the same zip. See [Icons](/icons#exporting). --- Source: https://resourcepack.ai/docs/rp-engine # RP Engine RP Engine is a plugin for Spigot, Paper and Folia servers (Minecraft 1.19.4 and newer). It adds things vanilla Minecraft does not have: swords with their own models, chairs you can sit in, emotes, custom sounds, icons in chat, artwork behind your menus, recipes, mobs, vehicles and liquids. You describe each one in a few lines of YAML in a folder on your server, the **content folder**. The plugin turns that folder into a resource pack (the zip of textures, models and sounds a Minecraft client downloads), sends it to every player who joins, and makes the content work on the server side. You never build or upload a zip yourself. ## Getting your content onto the server There are three ways in, and you can mix them: | You have | Do this | |---|---| | Your own YAML and art | Make a folder in `plugins/RPEngine/content/`. See [The content folder](/rp-engine/content) | | A pack exported from [Studio](https://studio.resourcepack.ai), or any resource pack `.zip` | Drop the `.zip` into `plugins/RPEngine/content/` and run `/rp reload`. See [Adding a resource pack](/rp-engine/resource-packs) | | A pack published in Studio that you want to keep up to date | Run `/rp distribute `, with the code from the pack's Distribution page. New releases arrive by themselves. See [Distribution](/distribution) | To try a Studio pack on yourself before anybody else sees it, use [`/rp sync`](/rp-engine/commands#studio) instead: it sends the pack to you alone and changes nothing on the server. Studio is optional RP Engine works entirely from files on disk. Studio makes the art with AI and can send it straight to a running server, which is faster, but you never need it. ## What it can hold | Content | What it is | |---|---| | [Custom blocks](/rp-engine/blocks) | A block you place, mine and stand on | | [Items](/rp-engine/items) | Sprites or 3D models, wearable as [armour](/rp-engine/armour), with real [vanilla stats](/rp-engine/stats) | | [Actions](/rp-engine/actions) | What an item does when it is used, hit with, and so on | | [Models](/rp-engine/models) | Put down, [sat on](/rp-engine/placement-options), [animated](/rp-engine/animation), [worn by a mob](/rp-engine/mobs) | | [Emotes](/rp-engine/emotes) | Worn or performed, alone or with other players | | [Sounds](/rp-engine/sounds) and [music](/rp-engine/music) | Real sound events with subtitles, and background playlists | | [Icons](/rp-engine/icons) | Pictures that behave like letters, anywhere text shows | | [GUIs](/rp-engine/screens) | A picture drawn behind a chest-style menu | | [HUD](/rp-engine/hud) | Overlays drawn over the game screen | | [Dialogs](/rp-engine/dialogs) | Minecraft's own pop-up screens, with buttons and inputs (1.21.6+) | | [Text Effects](/rp-engine/text-effects) and [VFX](/rp-engine/vfx) | Text that waves or burns, and spell effects in the world | | [Rank Tags](/rp-engine/rank-tags) | Drawn rank badges for chat and name tags | | [Recipes](/rp-engine/recipes) | Crafting, cooking, stonecutting, smithing, brewing, anvils | | [Entities](/rp-engine/entities) | Custom mobs wearing a model, with [skills](/rp-engine/skills), drops and spawners | | [Vehicles](/rp-engine/vehicles) | Cars, boats and aircraft players drive | | [Liquids](/rp-engine/liquids) | Pools with their own rules | ## Two ideas worth knowing **One ID for everything.** `mypack:ruby` is the item, the path to its art and what is stored on the item stack. There are no numbers to allocate. If another plugin's config refers to your content, write the ID. See [IDs and namespaces](/rp-engine/ids). **Reloads are cheap for players.** The same content always builds to the same pack, so a restart that changes nothing makes nobody download anything. See [Bundles](/rp-engine/bundles) and [Reloading](/rp-engine/reloading). ## Where to go next Installing The jar, what your server needs, and your first item. The content folder How a pack is laid out on disk, and what the warnings mean. Commands Every command and the permission it needs. Configuration Every setting in config.yml. --- Source: https://resourcepack.ai/docs/rp-engine/actions # Making items do things `actions:` makes an [item](/rp-engine/items) do something when it is used: play a sound, send a message, give an effect, run a command. You pick a trigger (such as a right-click) and list the steps to run, in order. Placed models and custom blocks take the same `actions:`. ```yaml wand: material: STICK model: wand actions: right_click: - cooldown: 5 - message: "&bWhoosh." - sound: mypack:chime - effect: SPEED 10 2 - console: "effect give {player} minecraft:levitation 3" ``` Each step is one key with its own `-`. One key per dash Two keys in one list entry means a dash is missing. YAML accepts it, so RP Engine reports it as a load error naming both keys, and that step is skipped. ## Triggers | Trigger | When | |---|---| | `right_click` | Right-clicked, on a block or in the air | | `left_click` | Left-clicked | | `attack` | Used to hit an entity | | `consume` | Eaten or drunk | | `drop` | Dropped | | `pickup` | Picked up off the ground | | `block_break` | Used to break a block | | `shoot` | Shot, for a bow or crossbow | | `break` | Ran out of durability | | `place` | Put down, as a [placed model](/rp-engine/models) or a [custom block](/rp-engine/blocks) | | `interact` | Right-clicked where it stands, as a placed model or a custom block | | `remove` | Punched out or mined by a player, as a placed model or a custom block | `break` runs after the item is already gone, so it cannot be cancelled. It is still useful for a sound or a message. There is no trigger for putting armour on or taking it off, and none for a player joining the server. For something on join, have a join-command plugin run the `/rp` command you want. ## The thing in the world `place`, `interact` and `remove` are about a placed model or custom block standing in the world, rather than the item in someone's hand. A doorbell: ```yaml doorbell: material: PAPER model: doorbell place: { surface: wall } actions: interact: - cooldown: 2 - sound: minecraft:block.bell.use - console: "say {player} is at the door" ``` - A custom block takes the same `actions:` in its own definition. - On `interact`, `cancel` stops what the click would otherwise do: nobody sits, nothing opens, and nothing is placed against the block. - `place` and `remove` run once the piece is down or gone, so they cannot be cancelled. - `take` does nothing in these three, because the click is on the piece, not the item in the player's hand. - On an item with no `place:` block, these triggers are a load warning, since they can never fire. ## Steps | Step | What it does | |---|---| | `message` | A line of chat to whoever used it. `&` colour codes | | `broadcast` | The same, to everybody | | `actionbar` | A line above their hotbar | | `console` | Runs a command as the console | | `run` | Runs a command as the player, with their own permissions | | `sound` | `mypack:chime`, or a vanilla key like `minecraft:block.anvil.land`. Optional volume and pitch after it | | `effect` | `SPEED 10 2`: type, seconds, level. Level 1 is the first level | | `particle` | `flame 12 0.3`: type, count, spread. See below | | `give` | `mypack:ruby 3`. What will not fit drops on the floor | | `take` | Takes this many off the stack | | `cancel` | Cancels the item's vanilla use | | `cooldown` | Seconds. **Stops the rest of the list** if it has not been that long | | `permission` | Stops the rest of the list unless the player has this permission | | `dialog` | `mypack:menu`, then any `name=value` pairs. Opens a [dialog](/dialogs) for the player. Needs Minecraft 1.21.6 | **`console` or `run`.** `console` can do things the player is not allowed to do themselves. `run` acts as the player and checks their permissions. **`cooldown` stops the list**, so put a `message` before it if you want the refusal to say something: ```yaml right_click: - message: "&7You steady yourself..." - cooldown: 30 - message: "&bAgain!" ``` **`cancel` stops the vanilla use.** Without it, a wand built on a bucket still fills with water. **`particle`** takes the game's own names, such as `flame` or `happy_villager`; names from before Minecraft 1.20.5 renamed them work too. Count defaults to 8 (up to 200) and spread to 0.3 blocks. Particles appear at the block or piece the action is about, or at the player for a held item. A particle that needs extra data, such as a colour or a block, draws nothing. A step that cannot run is skipped and the rest still run, so a misspelled potion costs only that line. ## Text Any text can include `{player}`, `{uuid}`, `{world}`, `{x}`, `{y}`, `{z}`, and any [PlaceholderAPI](/rp-engine/placeholderapi) placeholder if that plugin is installed. ```yaml - broadcast: "&e{player} found the shrine at {x} {y} {z}" ``` ## Going further Actions have no conditions, variables or branching, and that is deliberate. For anything more, write a small plugin that listens for [`ItemUseEvent`](/rp-engine/api), which carries the item ID, the stack, the click and the block. Cancelling that event cancels the vanilla use and stops the item's own actions running. --- Source: https://resourcepack.ai/docs/rp-engine/animation # Animation If a model has animations, the placed model moves: a windmill turns, a chest lid opens, a statue breathes. RP Engine plays them on its own, and you can change how each one plays on your server without editing the model. ![An animated Ferris wheel model, turning](/images/animations.webp) ## Where animations come from **From Blockbench.** Put the Blockbench project in `assets/models/` in your [content folder](/rp-engine/content) and RP Engine reads its bones and keyframes. There is nothing to declare and nothing to export. Projects saved by Blockbench 5 work too. ``` content/mypack/ items/furniture.yml assets/models/windmill.bbmodel ← bones and keyframes, as Blockbench saved it ``` Save the project, do not export it Blockbench's **File → Export → Java Block/Item model** writes cubes and nothing else: no bones, no keyframes. Save the `.bbmodel` project instead; it is the only file your animation is in. **From Studio.** A model animated in Studio's editor brings its animations and triggers with it when you send the pack to your server. See [Animations](/animations) for keyframing and triggers there. Everything below about controlling playback applies to both. ## When it plays The Blockbench file decides when each animation starts, unless you set a [`mode`](#what-happens-at-the-end) over it: | Set in Blockbench as | Plays | |---|---| | **Loop** | On its own, as soon as the piece is placed, for ever | | **Once** or **Hold** | When a player right-clicks the piece | Right-clicking a piece with a right-click animation plays it rather than sitting on it. Sneak and right-click to sit, if it has a `seat`. ### Playing from a plugin There is no `/rp` command that plays an animation. Other plugins play one by its name in Blockbench: from your own plugin, `Placement.play` in [the API](/rp-engine/api), and on a model worn by a mob, [MythicMobs](/rp-engine/mythicmobs)' `rpanimate`. ## Controlling playback An animation plays exactly as it was made unless you say otherwise. To change how one plays on your server, name it under `animations:` in the item's `place:` block: ```yaml chair: material: PAPER model: chair place: animations: spin: # the animation's name in Blockbench mode: loop # loop | hold | once, overriding the .bbmodel speed: 0.5 # half the authored speed priority: 10 # wins when two animations claim one trigger blend: 0.25 # seconds to ease in and out of it ``` Leave out any setting to keep what the model says. | Setting | Does | Default | |---|---|---| | `mode` | `loop`, `hold` or `once`: what happens at the end, and when it starts | From the model | | `speed` | Playback speed multiplier | `1` | | `priority` | Which animation wins a shared trigger (higher wins) | `0` | | `blend` | Seconds to ease in and out | Off | | `layer` | Which [layer](#layers) it plays on | `0` | | `bones` | Limits it to these bones (a [mask](#masks)) | Whole model | | `weight` | How far it moves what it touches, 0 to 1 | `1` | ### What happens at the end | `mode` | What happens | |---|---| | `loop` | Starts again | | `hold` | Stops on the last frame and stays there | | `once` | Plays, then goes back to rest | Use `hold` for a door, a lid or a drawbridge. Without it they spring shut the moment they finish opening. `mode` also decides when it starts, the same way the Blockbench setting does: `loop` plays on its own as soon as the piece is placed, and `hold` or `once` waits for a right-click. An animation whose model gives it other triggers keeps them, and `loop` adds playing on its own. Needs RP Engine 0.2.13 or newer; older versions change only the ending. ### Speed `speed: 0.5` is half as fast; `2` is twice as fast. The same walk cycle can be a stroll on one server and a sprint on another without editing the model. ### Priority Matters when a model has more than one animation on the same trigger, for example two right-click animations. Higher wins; with equal priority, the one that comes first in the file wins. ### Blend `blend:` is how many seconds the model takes to ease into and out of the animation, instead of snapping between poses. A quarter of a second suits most things. It is off unless you set it, because blending a quick flicker would smear it into nothing. Blend does nothing on a [vehicle](/rp-engine/vehicles): a vehicle's animations always switch instantly when its state changes. ## Layers and masks A layer lets one animation play on top of another, such as a wave over a walk. A mask limits an animation to part of a model, such as the upper body. Both go in the same `animations:` block: ```yaml place: animations: walk: { mode: loop, layer: 0 } wave: { mode: once, layer: 1, bones: [torso], blend: 0.2 } ``` ### Layers `layer: 0` is the base: a walk cycle or an idle. Only one base animation plays at a time, and starting another replaces it. Anything on layer 1 or higher plays on top of whatever is running, so a wave on layer 1 plays over the walk rather than replacing it. Each layer holds one animation, so waving again replaces the first wave and leaves the walk alone. The layer comes from these settings, so a plugin or command that plays an animation by name doesn't need to know about layers. ### Masks `bones:` limits the animation to the bones you name and everything attached under them. `bones: [torso]` moves the torso and the arms and head hanging off it, which is what "upper body only" usually means. Name the parent bone rather than listing every limb. Bone names are whatever you called them in Blockbench. A bone is either in the mask or not. There is no partial strength per bone; if you need the shoulder at half strength and the hand at full, author that into the animation itself. ### Weight `weight:` (0 to 1) scales how far the animation moves what it touches. Half a wave is a smaller wave. Rotation and position are scaled toward zero and scale toward 1, so a bone scaled to 2 at half weight ends up at 1.5. ## What an animated model costs The game cannot animate a block model, so an animated model is placed as one display entity per moving bone, plus one for everything that stays still, and the server updates their poses a few times a second. - **It costs entities.** A ten-bone model is eleven entities in the world. Use animated models as centrepieces, not something to place a hundred of. - **Bones are a tree.** Rotating a torso carries the arms inside it. A keyframe on a cube inside an animated bone plays inside the bone's movement; anything with no keyframes rides along as one piece. --- Source: https://resourcepack.ai/docs/rp-engine/api # Plugin API RP Engine has a Java API, so your own Spigot or Paper plugin can use what a server's pack holds: give a custom item, place a model, play an emote, park a vehicle, spawn a custom mob, show a HUD, open a dialog with your own values on it, and cancel any of those when your rules say no. Every snippet is shown in Java and Kotlin; pick one and the rest of the docs follows your choice. This page matches **RP Engine 0.2.82**. ## Setting up RP Engine is not published to a Maven repository. Download `RPEngine.jar` from [resourcepack.ai/rp-engine](https://resourcepack.ai/rp-engine), put it in your project's `libs/` folder and compile against it. Use `compileOnly`: the server already has the plugin, and a shaded second copy breaks class loading. ```groovy dependencies { compileOnly 'org.spigotmc:spigot-api:1.21.4-R0.1-SNAPSHOT' compileOnly files('libs/RPEngine.jar') } ``` ```kotlin dependencies { compileOnly("org.spigotmc:spigot-api:1.21.4-R0.1-SNAPSHOT") compileOnly(files("libs/RPEngine.jar")) } ``` RP Engine runs on Java 17 and Minecraft 1.19.4 or newer, so target Java 17 if you want your plugin to load everywhere the engine does. In your `plugin.yml`, tell the server to load RP Engine first: ```yaml depend: [RPEngine] # your plugin can't run without it # or softdepend: [RPEngine] # optional: check it is there before using it ``` ## Getting the API Everything hangs off the plugin instance. Fetch it in `onEnable`: ```java if (!(Bukkit.getPluginManager().getPlugin("RPEngine") instanceof RPEnginePlugin engine)) { getLogger().info("RP Engine isn't installed"); // only possible with softdepend return; } engine.items(); // custom items engine.models(); // models, and the ones standing in your worlds engine.blocks(); // custom blocks: which one stands here, placing one engine.liquids(); // custom liquids, and which one a player is in engine.emotes(); // emotes and movement sets engine.vehicles(); // vehicles, and the ones standing in your worlds engine.shaderObjects(); // 3D shader objects: place them and drive them engine.armor(); // 3D armour sets, and putting them on people engine.sounds(); // custom sounds engine.music(); // background music: playlists, one per player engine.icons(); // icons, and putting one into text engine.textEffects(); // Text Effects, and writing text in one engine.vfx(); // VFX: play one where somebody stands engine.transitions(); // Transitions: cover a screen, do something, uncover it engine.mobs(); // custom mobs: spawn one, animate one, give an egg engine.skills(); // mob skills: add a mechanic, condition or targeter; cast one engine.overlays(); // HUD overlays: show one, hide one, feed it values engine.dialogs(); // dialogs: open one, feed it values, read player settings engine.registry(); // everything this server holds, by id engine.registration(); // adding content of your own ``` ```kotlin val engine = Bukkit.getPluginManager().getPlugin("RPEngine") as? RPEnginePlugin ?: return logger.info("RP Engine isn't installed") // only possible with softdepend engine.items() // custom items engine.models() // models, and the ones standing in your worlds engine.blocks() // custom blocks: which one stands here, placing one engine.liquids() // custom liquids, and which one a player is in engine.emotes() // emotes and movement sets engine.vehicles() // vehicles, and the ones standing in your worlds engine.shaderObjects() // 3D shader objects: place them and drive them engine.armor() // 3D armour sets, and putting them on people engine.sounds() // custom sounds engine.music() // background music: playlists, one per player engine.icons() // icons, and putting one into text engine.textEffects() // Text Effects, and writing text in one engine.vfx() // VFX: play one where somebody stands engine.transitions() // Transitions: cover a screen, do something, uncover it engine.mobs() // custom mobs: spawn one, animate one, give an egg engine.skills() // mob skills: add a mechanic, condition or targeter; cast one engine.overlays() // HUD overlays: show one, hide one, feed it values engine.dialogs() // dialogs: open one, feed it values, read player settings engine.registry() // everything this server holds, by id engine.registration() // adding content of your own ``` What is API and what is not Everything in `ai.resourcepack.engine.api` (and `api.event`) is supported. Nothing in `ai.resourcepack.engine.core` is, and it can change in any release, including a patch. ## IDs Everything has one `namespace:path` ID, an ordinary Minecraft resource location. `parse` returns empty rather than throwing, so a bad ID in somebody's config becomes a message, not a stack trace. ```java ContentId ruby = ContentId.parse("mypack:ruby").orElseThrow(); ``` ```kotlin val ruby = ContentId.parse("mypack:ruby").orElseThrow() ``` **Store IDs, never what they resolve to.** An icon's codepoint moves when content changes and an item's model is derived from its ID. The ID is the only stable reference. ## Items ```java Optional stack = engine.items().create(ruby); Optional what = engine.items().idOf(hand); boolean isRuby = engine.items().is(hand, ruby); ``` ```kotlin val stack: Optional = engine.items().create(ruby) val what: Optional = engine.items().idOf(hand) val isRuby: Boolean = engine.items().`is`(hand, ruby) ``` Identity lives in the stack's persistent data, not its name or model. An item renamed in an anvil is still itself, and a vanilla diamond somebody named "Ruby" is not one. `create(id, amount)` makes a stack of several. A Studio Item is not an item here `items()` knows the items defined in a [content pack](/rp-engine/items)'s `items/` folder. An Item made in Studio is art plus a give command: a vanilla item wearing a `custom_model_data` string, which is on the item's page in Studio. So `items().create(studio:blank)` is empty, and `/rp reload` reports `0 definitions` for a Studio pack. To give a Studio Item an ID here, define it in a content pack of your own and point its `texture:` at the Studio picture, `minecraft:item/`, with the Studio pack still on the server. To make a stack of your own wear a pack's art without becoming that item, call `wearModel(stack, modelId)`. Don't set the item model yourself: below 1.21.4 the model is a number only the engine knows. `create` and `wearModel` are main thread only; `ids()` and `info()` are safe from any thread. ### Items made of parts For an item with [`parts:`](/rp-engine/items#tools-made-of-parts), set and read which part fills each slot: ```java ItemStack pick = engine.items().create(pickaxe).orElseThrow(); pick = engine.items().withParts(pick, Map.of( "head", goldHead, "handle", birchHandle)).orElseThrow(); Map parts = engine.items().partsOf(pick); ``` `withParts` returns a changed copy. Slots you leave out keep what they had. It returns empty if the stack isn't an item made of parts, or a slot or part isn't one the item's definition lists. `partsOf` answers every slot, with the first option for a slot that was never set. Only the look and the record of parts change: the name, lore and stats are yours to set. Main thread only. ## Models ```java engine.models().place(location, "golem", PlaceOptions.defaults()); // a Studio model engine.models().place(location, tree, PlaceOptions.defaults().placer(player)); // an item's place: block engine.models().itemFor("golem", ItemOptions.defaults()); engine.models().near(location, 16); // what is standing around here engine.models().at(entity); // is this entity part of a model? engine.models().at(entity).ifPresent(model -> model.play("wave", true)); // play on a placed model ``` ```kotlin engine.models().place(location, "golem", PlaceOptions.defaults()) // a Studio model engine.models().place(location, tree, PlaceOptions.defaults().placer(player)) // an item's place: block engine.models().itemFor("golem", ItemOptions.defaults()) engine.models().near(location, 16.0) // what is standing around here engine.models().at(entity) // is this entity part of a model? engine.models().at(entity).ifPresent { it.play("wave", true) } // play on a placed model ``` There are two ways to place: - **By model id** (a String): just the model. `PlaceOptions` sets a starting `animation`, a `scale` and a `placer`. - **By item `ContentId`**: exactly what a player placing that item gets (hitbox, seat, light, storage, states, animated rig, the item's `place` actions). With a `placer` set, [`ModelPlaceEvent`](#events) fires first, with `stack()` null. It returns empty when the item has no `place:` block, the block is occupied, or a listener cancelled it. A `Placement` is a handle on a model standing in a world: | Method | What it does | |---|---| | `modelId()`, `location()`, `hitbox()` | What it is and where; `hitbox()` is its Interaction entity | | `animations()`, `playing()` | Its animation names, and the one running | | `play(name)` | Plays an animation. Asking again for a one-shot that is mid-play is ignored | | `play(name, true)` | Starts it over even if it is already running | | `stop()`, `seek(seconds)`, `playhead()` | Stop, drive its clock yourself, read how far in it is | | `data()` | Persistent data saved with the model, for your own keys (`Placement.key(plugin, name)`) | | `remove(dropItem)`, `isValid()` | Break it, and check it still exists | **`play` returns false** when the model has no animation by that name, the model has no moving parts (one that places as a single still display can't animate), it has been broken, or that one-shot is already playing (use `play(name, true)` to restart it). It never throws. `near(location, radius)` and `in(chunk)` find placements; there is no "every model on the server" call. `isModel(entity)` says whether an entity belongs to any model. ### Models on entities that aren't ours `bind(entity, model)` (optionally with a scale) puts a model on an NPC or a boss, `unbind` takes it off, `modelOn(entity)` says which one it wears, and `animate(entity, name)` / `stopAnimating(entity)` play it. **`animate` returns false** when the entity wears nothing of ours, or its model has no animation by that name. It is only for a bound model: a model standing in the world, including the hitbox a right-click hands you, also answers false. For one of those, use `at(entity)` and `play` on the placement, as above. ### What the pack says about a model What a pack's `place:` block said is a read-only `ModelInfo`: facing, scale, seat and light, plus `storage()` (a `StorageSpec`: type, rows, title, sounds), `jukebox()`, `states()` with `nextState`, `lightIn` and `solidIn`, `grow()`, and `variation()` (the random turn and size it is placed with). The engine handles the clicks itself; cancel `ModelInteractEvent` to stop one. Growing fires neither `ModelBreakEvent` nor `ModelPlaceEvent`. See [Working furniture](/rp-engine/furniture). ### Sitting somebody down `sit(player, location)` sits a player at a place the way a chair does, with no model needed: a `/sit` command, a bench that is only blocks, a cutscene. The location is the surface they sit on, and its yaw is the way they face. ```java engine.models().sit(player, bench); // false if they are already sitting or riding engine.models().isSeated(player); // on a chair, a seat bone, or sit() engine.models().stand(player); // get them up ``` ```kotlin engine.models().sit(player, bench) // false if they are already sitting or riding engine.models().isSeated(player) // on a chair, a seat bone, or sit() engine.models().stand(player) // get them up ``` It asks [`ModelSeatEvent`](#events) like any other seat, so a plugin that refuses sitting refuses this too. They get up by sneaking. A vehicle's seat is not one of these: use `engine.vehicles().of(player)` for that. Needs RP Engine 0.2.82 or newer. ## Custom blocks A [custom block](/rp-engine/blocks) is a real block in the world, so Bukkit's own `BlockPlaceEvent` and `BlockBreakEvent` fire for it like any other block. What the API adds is the question those events can't answer: is this block one of the pack's, and which one. ```java Blocks blocks = engine.blocks(); ContentId ruby = ContentId.parse("mypack:ruby_ore").orElseThrow(); blocks.at(block); // Optional: the custom block standing here blocks.idAt(block); // just its id blocks.is(block, ruby); // is it this one? blocks.stateAt(block); // "facing=north,lit=true", or "" for a block with one state blocks.place(block, ruby); // put one here, replacing what stands there blocks.setProperty(block, "lit", "true"); // change one property, keep the rest @EventHandler public void onBreak(BlockBreakEvent event) { if (engine.blocks().is(event.getBlock(), ruby)) { quests.mined(event.getPlayer(), "ruby"); } } ``` ```kotlin val blocks = engine.blocks() val ruby = ContentId.parse("mypack:ruby_ore").orElseThrow() blocks.at(block) // Optional: the custom block standing here blocks.idAt(block) // just its id blocks.`is`(block, ruby) // is it this one? blocks.stateAt(block) // "facing=north,lit=true", or "" for a block with one state blocks.place(block, ruby) // put one here, replacing what stands there blocks.setProperty(block, "lit", "true") // change one property, keep the rest @EventHandler fun onBreak(event: BlockBreakEvent) { if (engine.blocks().`is`(event.block, ruby)) { quests.mined(event.player, "ruby") } } ``` `place` is a plain set: no event fires, no item is taken, no sound plays and the neighbours are not updated. It returns false when there is no such block or the pack has no state left for it. `setState(block, state)` and `setProperty` return false for a shaped block (a stair, a slab, a door), whose state is the game's own block data, so change that through Bukkit. `BlockInfo` is what the pack said: `shape()`, `properties()`, `defaultState()`, and `with(state, property, value)` to work a state out without touching the world. To give somebody the block's item, use `engine.items()` with the same id. Needs RP Engine 0.2.82 or newer. ## Liquids A [custom liquid](/rp-engine/liquids) is water or lava that counts as something else inside a pool the server owner marked out. ```java engine.liquids().ids(); // every liquid engine.liquids().info(id); // its base, effect and damage engine.liquids().at(location); // the liquid whose pool this place is in engine.liquids().of(player); // the liquid this player is in right now ``` ```kotlin engine.liquids().ids() // every liquid engine.liquids().info(id) // its base, effect and damage engine.liquids().at(location) // the liquid whose pool this place is in engine.liquids().of(player) // the liquid this player is in right now ``` `at` asks about the pool, so a bridge over the acid answers too. `of` is stricter: in a pool and actually wet, as the engine last saw it (it looks once a second). [`PlayerLiquidEvent`](#events) tells you the moment that changes. Needs RP Engine 0.2.82 or newer. ## Emotes ```java engine.emotes().play(player, "wave"); // solo engine.emotes().play(lead, "hug", List.of(other)); // with a cast engine.emotes().canPerform(player); engine.emotes().isEmoting(player.getUniqueId()); engine.emotes().playing(player); // Optional: which one (0.2.82) engine.emotes().stop(player); ``` ```kotlin engine.emotes().play(player, "wave") // solo engine.emotes().play(lead, "hug", listOf(other)) // with a cast engine.emotes().canPerform(player) engine.emotes().isEmoting(player.uniqueId) engine.emotes().playing(player) // Optional: which one (0.2.82) engine.emotes().stop(player) ``` A cast is moved, so ask them first An emote with a cast teleports the people it names. The engine's own `/emote` sends an invitation first; `play` does not, so asking is your job. `EmoteResult` carries a typed reason rather than a sentence, so you write the message in your own words and language. ### Putting a rig on somebody yourself ```java engine.emotes().wear(player, "rowing"); // again to swap, null to take off engine.emotes().face(player, 90f); // point the body; null follows their look engine.emotes().seek(player, seconds); // pose the rig at this moment of its emote engine.emotes().seekProp(player, "skate_right", clock); // drive one carried prop's clock ``` ```kotlin engine.emotes().wear(player, "rowing") // again to swap, null to take off engine.emotes().face(player, 90f) // point the body; null follows their look engine.emotes().seek(player, seconds) // pose the rig at this moment of its emote engine.emotes().seekProp(player, "skate_right", clock) // drive one carried prop's clock ``` `wear` is a movement set where you, not the player's legs, decide what the rig wears. Moving doesn't end it, and calling it again swaps without restarting. `Emotes.BUILT_IN_SITTING` and `BUILT_IN_STANDING` work on any pack. - `face` is for a passenger whose body belongs to a seat. Call it every tick with the seat's direction. It only affects a rig you put on with `wear`. - `seek`, called every tick with a placement's `playhead()`, keeps a rig in step with a model's animation (a paddler's arms on a paddle). - `seekProp` drives a carried prop by your own clock, such as a wheel that turns with distance travelled. It survives a swap to another emote carrying the same prop. - `anchor(player, feet)` pins the rig to a point you move every tick (a seat you move yourself), so the two arrive together; `null` hands it back. - `lean(player, pitch, roll)` tips the rig in the wearer's own frame, such as a rider leaning into a corner. It holds until you set it again. - `wear(player, id, under)` layers the emote over one of the built-in stances, for an emote that animates only some bones. ### Carrying a rig on a seat of your own A worn rig follows its wearer by being teleported every tick, which the client smooths out, so on anything fast it trails behind. Mount the rig's displays on your seat instead and the client draws them wherever the seat is: ```java int[] ids = engine.emotes().passengerEntityIds(rider); // bones, carried models, hands double lift = engine.emotes().rigOriginOffset(); // blocks above the feet ``` ```kotlin val ids = engine.emotes().passengerEntityIds(rider) // bones, carried models, hands val lift = engine.emotes().rigOriginOffset() // blocks above the feet ``` Every display hangs off one point, `rigOriginOffset()` above the rider's feet, so put your seat's passenger position there. Read the number rather than copying it, as it follows the size the engine draws players at. Mount with a packet, not addPassenger The engine teleports every display every tick, and a Bukkit teleport of a passenger dismounts it. Send a client-side passengers packet instead. That packet is the vehicle's **whole** list: include whoever really sits there, resend it when the server sends its own, and send it to anybody who starts seeing the seat. The ids change: putting a rig on spawns every display, and swapping to an emote with different carried models spawns those again. `EmoteRigSpawnEvent` fires each time with the new list, so mount there. It fires for every rig, so check the player is yours. ### Rebuilding the rigs A player's rig wears their skin, and rigs are baked into a pack. The engine rebakes when a new skin arrives but only sends that build to whoever joins next. To make everybody see everybody's current skin now (a minigame dressing players in emotes), call `engine.reloadRigs()` on the main thread. On 1.20.3+, where packs stack, that resends only the small rig pack and fires `RigPackBuildEvent`; on older versions it is a full `reload()`. ## 3D armour ```java ContentId santa = ContentId.parse("christmas:santa").orElseThrow(); engine.armor().available(); // false before 1.21.4 engine.armor().info(santa); // its name and pieces engine.armor().create(santa, ArmorPiece.HELMET); // one piece, as an item ArmorResult result = engine.armor().wear(player, santa); // the whole set, now engine.armor().wearing(player); // which set each worn piece is from engine.armor().strip(player); // every 3D piece off ``` ```kotlin val santa = ContentId.parse("christmas:santa").orElseThrow() engine.armor().available() // false before 1.21.4 engine.armor().info(santa) // its name and pieces engine.armor().create(santa, ArmorPiece.HELMET) // one piece, as an item val result = engine.armor().wear(player, santa) // the whole set, now engine.armor().wearing(player) // which set each worn piece is from engine.armor().strip(player) // every 3D piece off ``` A set from a content folder is `namespace:path`; one pushed from Studio is `studio:`. Each piece is an ordinary item that goes on by hand like armour, so `wear` is a shortcut for all four. Whatever was in a slot goes back to the player (or drops at their feet if their inventory is full) and is listed in `ArmorResult.displaced()`. `strip` removes only 3D pieces and gives them to nobody. `ArmorResult` has a reason: `WORN`, `UNKNOWN_SET` or `UNSUPPORTED`. A set pushed from Studio is only drawn for players holding that push's pack. Main thread only, except `available`, `ids` and `info`. See [3D armour](/rp-engine/armour). ## 3D shader objects Needs RP Engine 0.2.10 or newer, and a server on Minecraft 1.21.4 or newer. `engine.shaderObjects()` places and drives [3D objects](/rp-engine/objects): ```java ShaderObjects objects = engine.shaderObjects(); if (!objects.supported()) return; // false before 1.21.4 ContentId nuke = ContentId.parse("studio:nuke").orElseThrow(); ShaderObject bomb = objects.spawn(location, nuke).orElseThrow(); bomb.moveBy(new Vector(0, -20, 0), 50, Easing.IN); // over 50 ticks bomb.turnTo(90, 0, 0, 40, Easing.IN_OUT); // yaw, pitch, roll bomb.resize(40, 2, Easing.LINEAR); // diameter in blocks bomb.state("detonate"); // starts its clock bomb.play("drop"); // a sequence from objects/ ``` ```kotlin val objects = engine.shaderObjects() if (!objects.supported()) return // false before 1.21.4 val nuke = ContentId.parse("studio:nuke").orElseThrow() val bomb = objects.spawn(location, nuke).orElseThrow() bomb.moveBy(Vector(0, -20, 0), 50, Easing.IN) // over 50 ticks bomb.turnTo(90f, 0f, 0f, 40, Easing.IN_OUT) // yaw, pitch, roll bomb.resize(40.0, 2, Easing.LINEAR) // diameter in blocks bomb.state("detonate") // starts its clock bomb.play("drop") // a sequence from objects/ ``` `spawn(location, id, size)` sets the size; without it the object's own size is used. `at(entity)`, `near(location, radius)` and `loaded()` find objects already placed, and `ids()` and `info(id)` list what the server has (states, sequences, size). On a handle, `replay()`, `settle()`, `seed(n)`, `moveTo`, `stop()` and `remove()` match the [commands](/rp-engine/objects#commands); `state(name)` and `play(name)` return false for a name the object doesn't have. A time of 0 ticks is instant. Easing is `LINEAR`, `IN`, `OUT` or `IN_OUT`. A handle lasts as long as its entity, and the object's state, place, turn and size survive a restart; a running sequence or move does not. Main thread only, except `ids` and `info`. ## Sounds ```java engine.sounds().play(player, id); // only this player hears it engine.sounds().playAt(location, id); // everybody nearby hears it here engine.sounds().playFrom(entity, id); // everybody nearby hears it follow this entity engine.sounds().stop(player, id); // end it early for this player ``` ```kotlin engine.sounds().play(player, id) // only this player hears it engine.sounds().playAt(location, id) // everybody nearby hears it here engine.sounds().playFrom(entity, id) // everybody nearby hears it follow this entity engine.sounds().stop(player, id) // end it early for this player ``` All three use the sound's declared category, volume and pitch, and each has an overload that takes `volume` and `pitch`. Use `playFrom` for anything that moves. Each returns false for an unknown id. A stereo file plays at full volume wherever it was played from (Minecraft only places mono sounds in the world), so use mono for anything heard from a spot. Playing and stopping are main thread only; `ids()` and `info()` are safe from any thread. ## Music [Background music](/rp-engine/music) is a playlist of the pack's sounds. Each player hears one piece at a time: what your plugin started for them, otherwise the music of the place they stand in. ```java Music music = engine.music(); music.play(player, bossTheme); // from its first track, until stopped music.skip(player); // on to the next track music.stop(player); // end it; the place's music comes back music.playing(player); // the piece playing for them, if any music.track(player); // and the track ``` ```kotlin val music = engine.music() music.play(player, bossTheme) // from its first track, until stopped music.skip(player) // on to the next track music.stop(player) // end it; the place's music comes back music.playing(player) // the piece playing for them, if any music.track(player) // and the track ``` `play` beats the place's music, so a boss fight can start its own and `stop` it when the boss dies. `play` returns false for an unknown id, `skip` when nothing is playing. Calling `stop` with nothing started silences the place's music until they leave that place. Main thread only, except `ids()` and `info()`. ## HUD overlays An overlay is a picture kept on a player's screen: a stat block, a health bar, a crouch indicator. [Shader objects](/shaders) made in Studio are overlays, and so are the ones in a [`huds/` folder](/rp-engine/hud). Server owners draw them; your plugin decides who sees one and what numbers are in it. ```java engine.overlays().show(player, "studio:health"); // stays until hidden engine.overlays().hide(player, "studio:health"); engine.overlays().hideAll(player); engine.overlays().showing(player); // what they have on ``` ```kotlin engine.overlays().show(player, "studio:health") // stays until hidden engine.overlays().hide(player, "studio:health") engine.overlays().hideAll(player) engine.overlays().showing(player) // what they have on ``` An overlay made in Studio has the id `studio:`, where `` is the one on its card on the pack page. There is no duration: to show one for five seconds, schedule the `hide`. ### Feeding it values An overlay's labels and progress bars can print `{name}` placeholders. Any name works. ```java engine.overlays().set(player, "stamina", "40"); engine.overlays().set(player, "stamina", null); // remove it engine.overlays().value(player, "stamina"); // what you last set ``` ```kotlin engine.overlays().set(player, "stamina", "40") engine.overlays().set(player, "stamina", null) // remove it engine.overlays().value(player, "stamina") // what you last set ``` A placeholder is looked up in this order, and the first answer wins: 1. Whatever you `set`. A built-in with the same name never overrules it. 2. The built-ins: `player`, `name`, `displayname`, `uuid`, `world`, `x`, `y`, `z`, `direction`, `health`, `health_max`, `health_percent`, `food`, `air`, `level`, `xp`, `xp_points`, `xp_needed`, `ping`, `gamemode`, `online`, `max_online`, `time`, `day`. See [HUD overlays](/rp-engine/hud). 3. PlaceholderAPI, if the server has it. A name none of them knows draws as nothing rather than as `{name}`. Values are per player, not per overlay, and a progress bar reads the same names, so a stamina bar out of 100 needs only the one `set` call. They are also the values [dialogs](#dialogs) print. The same values can change more than words. A piece of a Studio overlay can be told, in its **From code** settings, to show only while a condition holds, to switch to one of its named colours, or (a progress bar) to take its length or a colour threshold from a value. Your plugin just sets the value: ```java engine.overlays().set(player, "status", "poisoned"); // a named colour engine.overlays().set(player, "rank", "vip"); // Show when {rank} == "vip" engine.overlays().set(player, "mana_len", "120"); // a bar 120 pixels long ``` ```kotlin engine.overlays().set(player, "status", "poisoned") // a named colour engine.overlays().set(player, "rank", "vip") // Show when {rank} == "vip" engine.overlays().set(player, "mana_len", "120") // a bar 120 pixels long ``` Colours can only be ones the overlay names, and shapes can't change at all: they are compiled into the resource pack. See [Changing it from code](/shaders#changing-it-from-code). `set` and `value` are safe from any thread. They only record the value; the next tick draws it, so six `set` calls in a row cost one redraw, and setting a value to what it already was costs nothing. `show`, `hide` and `hideAll` are main thread only. ### Laying a value out To build a line from several pieces (a kill feed: name, weapon icon, name), use the engine's own measurements: ```java int nameWidth = engine.overlays().width("Steve"); // pixels the cursor moves String gap = engine.overlays().space(5); // five pixels of nothing String back = engine.overlays().space(-12); // twelve pixels back, to draw over ``` ```kotlin val nameWidth = engine.overlays().width("Steve") // pixels the cursor moves val gap = engine.overlays().space(5) // five pixels of nothing val back = engine.overlays().space(-12) // twelve pixels back, to draw over ``` `width` knows vanilla's letters, every icon in the pack and the spaces `space` makes. Both work in any text drawn in the default font. ## Dialogs A [dialog](/dialogs) is a screen of its own, such as a store, a settings menu or a punish menu, on Minecraft 1.21.6 and newer. Server owners make them in Studio or in a `dialogs/` folder; your plugin decides when one opens and what values are on it. ```java engine.dialogs().show(player, "studio:shop"); engine.dialogs().close(player); engine.dialogs().ids(); // what this server has engine.dialogs().info(id); // name, command, settings it declares engine.dialogs().supported(); // false before 1.21.6 engine.dialogs().canShow(player, id); // would show get as far as the client? engine.dialogs().showing(player); // the dialog they were last shown, if it still counts ``` ```kotlin engine.dialogs().show(player, "studio:shop") engine.dialogs().close(player) engine.dialogs().ids() // what this server has engine.dialogs().info(id) // name, command, settings it declares engine.dialogs().supported() // false before 1.21.6 engine.dialogs().canShow(player, id) // would show get as far as the client? engine.dialogs().showing(player) // the dialog they were last shown, if it still counts ``` A dialog made in Studio has the id `studio:`, where `` is the one in its editor, and each page after the first is `studio:.`. `show` returns false rather than throwing when the server is older than 1.21.6, there is no such dialog, the player is offline, or they don't hold the pack the dialog's picture is in. `canShow` checks all of that first. What it can't promise is that the game accepts the dialog's JSON; a refusal is logged to the console. A dialog can declare a command players open it with (`/shop`). The engine registers it; `DialogInfo.command()` and `permission()` say what it is. `DialogInfo.quickAction()` says whether it is on the [Quick Actions key](/dialogs#the-quick-actions-key) (G). A dialog opens straight away even if it was pushed a moment ago. `pending()` only tells you whether its id is in the server's registry yet, which matters only to a datapack or command block of your own that names it. `showing(player)` is the dialog a player was last shown, until the server closes it or ten minutes pass with no click in it. A player who presses Escape tells nobody, so read it as "may still be clicking in it", not "is on their screen". ### When a player clicks a button A button runs a command, so the usual way to react is to make that command yours: register `/buy` (or whatever the button runs) in your `plugin.yml` and handle it in your command executor. The command runs as the player who clicked, with `{name}` placeholders already filled in. A button can run several commands in order, and a **Run as console** button runs its command as the console instead. Since RP Engine 0.2.82 there are two events as well, for rules that sit on top of somebody else's dialog: ```java @EventHandler public void onOpen(DialogOpenEvent event) { if (combat.isTagged(event.getPlayer())) { event.setCancelled(true); // their screen stays as it is } } @EventHandler public void onClick(DialogClickEvent event) { // event.dialog() is the dialog, event.command() what the click runs ("buy sword") if (event.command().startsWith("buy ") && !bank.canAfford(event.getPlayer())) { event.setCancelled(true); // the command never runs } } ``` ```kotlin @EventHandler fun onOpen(event: DialogOpenEvent) { if (combat.isTagged(event.player)) { event.isCancelled = true // their screen stays as it is } } @EventHandler fun onClick(event: DialogClickEvent) { // event.dialog() is the dialog, event.command() what the click runs ("buy sword") if (event.command().startsWith("buy ") && !bank.canAfford(event.player)) { event.isCancelled = true // the command never runs } } ``` - **`DialogOpenEvent`** fires every time a dialog is drawn, and a dialog is drawn again when a page turns, an item moves or a setting changes. `followed()` is true for those, so check it before greeting or charging anybody. - **`DialogClickEvent`** is a click that reaches the server as a command. A link that opens a URL, copies text, or turns to a page the client already holds never reaches the server, and neither does a plain Close, so there is no event for those. For typed inputs and an action per button in Java, use [Dialog Engine](/dialog-engine), a separate plugin built for that. [`DialogSlotMoveEvent`](#events) covers item slots. ### Values on it A dialog's words can print `{name}` placeholders, on its screen as well as in its title, tooltips, buttons and commands. See [Live values](/dialogs#live-values). Hand values over as you open it: ```java engine.dialogs().show(staff, "studio:punish", Map.of("target", suspect.getName())); // "Punish {target}" opens as "Punish Steve", the name and the face on its card are Steve's, // and a reason that runs "mute {target} 1h" runs "mute Steve 1h". ``` ```kotlin engine.dialogs().show(staff, "studio:punish", mapOf("target" to suspect.name)) // "Punish {target}" opens as "Punish Steve", the name and the face on its card are Steve's, // and a reason that runs "mute {target} 1h" runs "mute Steve 1h". ``` Or publish a value once, for every dialog and HUD that prints it. These are the same values `overlays().set` publishes, one set per player: ```java engine.dialogs().set(player, "coins", String.valueOf(balance)); engine.dialogs().set(player, "coins", null); // remove it engine.dialogs().value(player, "coins"); // what you last set ``` ```kotlin engine.dialogs().set(player, "coins", balance.toString()) engine.dialogs().set(player, "coins", null) // remove it engine.dialogs().value(player, "coins") // what you last set ``` A [list](/dialogs#lists-the-server-fills) (rows drawn in Studio, one per item) is filled all at once: ```java engine.dialogs().list(player, "warps", List.of("Spawn", "Shop", "Arena")); // More than one field a row: "" is the row's own value, "note" is {warps_note}. engine.dialogs().listRows(player, "warps", List.of(Map.of("", "Spawn", "note", "Where you start"))); ``` ```kotlin engine.dialogs().list(player, "warps", listOf("Spawn", "Shop", "Arena")) // More than one field a row: "" is the row's own value, "note" is {warps_note}. engine.dialogs().listRows(player, "warps", listOf(mapOf("" to "Spawn", "note" to "Where you start"))) ``` It sets `warps_1`, `warps_2` and so on plus `warps_count`, and clears items a longer list set before. Rows past the end are hidden, clicks and all. The command that opens a dialog can pass a list too, `warps=Spawn,Shop,Arena`, for that opening only. A placeholder is looked up in this order, and the first answer wins: 1. What you passed to `show` (case-insensitive). 2. What you published with `set` (or `overlays().set`). 3. The built-ins, the same ones a HUD has, all about the player viewing it. 4. PlaceholderAPI, if the server has it. 5. The player's own [settings](#player-settings). Settings come last because players change them themselves with a command. A setting can never stand in for a real value, but a setting that shares a name with anything above shows that value instead, so give settings names of their own. A name nothing answers is left as written, so a dialog that says `{VIP}` stays as it is. Formatting codes are removed from values. On a Studio dialog's screen, a value is limited to characters the game's small font draws (others become `?`) and is cut short with "…" if it doesn't fit its line. **A dialog is drawn once, as it opens.** A value that changes while it is on screen shows next time. Call `reopen` after a click changed something; it opens the dialog again with the values it was opened with: ```java // A Buy button on the store runs /buy sword. In your command: economy.withdraw(player, price); engine.dialogs().set(player, "coins", String.valueOf(economy.getBalance(player))); engine.dialogs().reopen(player); // the store again, with the new balance on it ``` ```kotlin // A Buy button on the store runs /buy sword. In your command: economy.withdraw(player, price) engine.dialogs().set(player, "coins", economy.getBalance(player).toString()) engine.dialogs().reopen(player) // the store again, with the new balance on it ``` The server isn't told when a player closes a dialog, so `reopen` opens it whether it is still on screen or not. Call it in answer to a click, not on a timer. ### Player settings A switch, slider or choice on a Studio dialog can be bound to a [player setting](/dialogs#player-settings): every player has their own value, the control shows it, and clicking it changes it. Read or change one from your plugin: ```java engine.dialogs().setting(player, "show_sidebar"); // Optional: "on" or "off" engine.dialogs().setSetting(player, "show_sidebar", "off"); // as if they clicked it engine.dialogs().setSetting(player, "show_sidebar", null); // back to the default engine.dialogs().info(id).map(DialogInfo::variables); // {"show_sidebar": ["on", "off"]} ``` ```kotlin engine.dialogs().setting(player, "show_sidebar") // Optional: "on" or "off" engine.dialogs().setSetting(player, "show_sidebar", "off") // as if they clicked it engine.dialogs().setSetting(player, "show_sidebar", null) // back to the default engine.dialogs().info(id).map(DialogInfo::variables) // {"show_sidebar": ["on", "off"]} ``` Settings are stored on the player and survive restarts. PlaceholderAPI reads them as `%rpengine_var_%`. Limits: | | | | --- | --- | | Name | lower-case letters, digits and `_`, up to 32 characters | | Value | letters, digits, `_`, `.` and `-`, up to 32 characters | | Per player | 64 settings | `setSetting` returns false for anything outside those. Your plugin may set any name, not only one a dialog declares. Nothing reopens on its own, so call `reopen` if they're looking at it. ### Your own container in a dialog A Studio dialog can have a grid of item slots showing a container "from a plugin", by name. Register one under that name and the grid shows your inventory for whoever opens it, and lets them move items in and out where the grid allows it: ```java engine.dialogs().container("bank", new DialogContainer() { @Override public Inventory inventory(Player viewer) { return banks.of(viewer); } @Override public boolean mayPlace(Player viewer, int slot, ItemStack stack) { return !stack.getType().name().endsWith("SHULKER_BOX"); } @Override public void changed(Player viewer) { banks.save(viewer); // after every move that touched it } }); ``` ```kotlin engine.dialogs().container("bank", object : DialogContainer { override fun inventory(viewer: Player): Inventory = banks.of(viewer) override fun mayPlace(viewer: Player, slot: Int, stack: ItemStack): Boolean = !stack.type.name.endsWith("SHULKER_BOX") override fun changed(viewer: Player) { banks.save(viewer) // after every move that touched it } }) ``` The engine reads your inventory as each dialog opens and writes to it as each move happens, on the main thread. A move reads both slots at that moment, so a stale screen can't duplicate items. `DialogSlotMoveEvent` fires before every move in any container. `set` and `value` are safe from any thread. Everything else in dialogs touches a player and is main thread only. ## Vehicles ```java engine.vehicles().spawn(location, id); // park one, ready to get into engine.vehicles().of(player); // the vehicle they are in engine.vehicles().at(entity); // is this thing part of a vehicle? engine.vehicles().near(location, 16); // nearest first engine.vehicles().loaded(); // every one in a loaded chunk engine.vehicles().isRiding(uuid); // safe from any thread ``` ```kotlin engine.vehicles().spawn(location, id) // park one, ready to get into engine.vehicles().of(player) // the vehicle they are in engine.vehicles().at(entity) // is this thing part of a vehicle? engine.vehicles().near(location, 16.0) // nearest first engine.vehicles().loaded() // every one in a loaded chunk engine.vehicles().isRiding(uuid) // safe from any thread ``` A `Vehicle` is a handle on one standing in a world, occupied or not: ```java Vehicle car = engine.vehicles().of(player).orElseThrow(); car.speed(); // blocks per second, negative in reverse car.states(); // MOVING, TURNING, AIRBORNE, IDLE ... car.driver(); // Optional car.occupants(); // driver first, then in seat order car.seat(other, 1); // put somebody in seat 1 car.eject(other); // and take them out car.submersion(); // how deep in water, in blocks. 0 out of it car.pointOn(-0.7, 0.6, 1.5); // where a point on the bodywork is, in the world ``` ```kotlin val car = engine.vehicles().of(player).orElseThrow() car.speed() // blocks per second, negative in reverse car.states() // MOVING, TURNING, AIRBORNE, IDLE ... car.driver() // Optional car.occupants() // driver first, then in seat order car.seat(other, 1) // put somebody in seat 1 car.eject(other) // and take them out car.submersion() // how deep in water, in blocks. 0 out of it car.pointOn(-0.7, 0.6, 1.5) // where a point on the bodywork is, in the world ``` `spawn` asks [`VehicleSpawnEvent`](#events) first and returns empty when a plugin cancels it. `car.remove()` fires `VehicleRemoveEvent` while the vehicle is still whole, which is the moment to read anything you kept in its `data()`. Both need RP Engine 0.2.82 or newer. `submersion()` is a depth; `VehicleState.SUBMERGED` only means "in a water block", which a puddle also is. A vehicle whose `medium` isn't `water` floods and stops in water; whether that wrecks it is up to you. Vehicle definitions can carry `addons:` blocks for your plugin. Read yours with `vehicle.info().addon("my-addon")`; the engine passes it through untouched. ### Fuel, and anything else that stops a vehicle going `setEnabled(false)` is the switch. A disabled vehicle ignores its driver and coasts to a halt, still falls and floats, and people get in and out as normal. The flag is saved on the chassis, so a car that ran dry is still dry after a restart. ```java NamespacedKey fuel = car.key(this, "fuel"); @EventHandler public void onState(VehicleStateEvent event) { // Burn only while it is actually going somewhere. if (event.entered(VehicleState.MOVING)) burners.add(event.vehicle()); if (event.left(VehicleState.MOVING)) burners.remove(event.vehicle()); } // once a second for (Vehicle vehicle : burners) { int left = vehicle.data().getOrDefault(fuel, PersistentDataType.INTEGER, 0) - 1; vehicle.data().set(fuel, PersistentDataType.INTEGER, Math.max(0, left)); vehicle.setEnabled(left > 0); } ``` ```kotlin val fuel = car.key(this, "fuel") @EventHandler fun onState(event: VehicleStateEvent) { // Burn only while it is actually going somewhere. if (event.entered(VehicleState.MOVING)) burners += event.vehicle() if (event.left(VehicleState.MOVING)) burners -= event.vehicle() } // once a second for (vehicle in burners) { val left = vehicle.data().getOrDefault(fuel, PersistentDataType.INTEGER, 0) - 1 vehicle.data().set(fuel, PersistentDataType.INTEGER, maxOf(0, left)) vehicle.setEnabled(left > 0) } ``` `data()` is the chassis's persistent data and survives everything the vehicle does. `uniqueId()` is the chassis's id and the one stable key: seats and model entities get new ids on every chunk load, so never store those. | Method | What it does | Saved? | | --- | --- | --- | | `setEnabled(boolean)` | Ignores the driver and coasts to a halt | Yes | | `setSpeedLimit(bps)` | Lower top speed, braking and reverse scaled to match. An aircraft limited below takeoff speed can't take off | No | | `setHandling(speed, turn)` | Scales what it can do, as fractions of its definition | No | | `setDamage(VehicleDamage)` | Per-wheel condition, engine power and steering pull, read by the handling model | No | | `setDescent(bps)` | An aircraft comes down at this rate whatever it's doing. 0 holds height, negative clears it | No | | `setPosture(pitch, roll)` | A drawn lean on top of the physics | No | | `stop()` | Dead this tick, like hitting a wall | | Re-apply the unsaved ones when you pick a vehicle up again (after a chunk load or restart). `VehicleDamage.NONE` is the vehicle exactly as its pack defines it: ```java car.setDamage(VehicleDamage.builder() .wheel(VehicleCorner.FRONT_LEFT, 0) // torn off .wheel(VehicleCorner.REAR_LEFT, 0.45) // buckled .enginePower(0.7) .steeringPull(-3) // pulls left .build()); ``` ```kotlin car.setDamage(VehicleDamage.builder() .wheel(VehicleCorner.FRONT_LEFT, 0.0) // torn off .wheel(VehicleCorner.REAR_LEFT, 0.45) // buckled .enginePower(0.7) .steeringPull(-3.0) // pulls left .build()) ``` A wheel runs from 1 (sound) to 0 (gone). Damage is not health and never changes the art; the engine has no opinion on how much punishment a vehicle takes. That is yours to track in `data()`. Who may get in is an event, not a method There is no `setLocked`. Cancel `VehicleEnterEvent` and they stay standing. `VehicleExitEvent` can't be cancelled, so a player is never trapped; to keep somebody in a race, put them back with `seat`. ### Collisions and parts `VehicleImpactEvent` fires once per meaningful collision (`cause()`: `VEHICLE`, `WORLD` or `LANDING`). `first()` and, for a vehicle pair, `second()` each carry the velocity before and the change, the contact normal, closing speed, impulse, spin change, `area()` (which side took it) and `contactOffset()` (where on the vehicle, in its own frame: `x` right, `y` up from its base, `z` forward). A zero offset means the engine can't say where. For `WORLD` impacts it is a face, not a point. To react: - `applyImpulse(deltaVelocity, spinDelta)` changes the physical response; `velocity()` reads it. An upward part lifts a land vehicle off the ground and gravity brings it back, so a jump pad is one call (RP Engine 0.2.45 and newer). - `scuff(area, contact, amount)` adds a persistent scrape (amount 0 to 1, at most ten marks; a repeat hit in the same place deepens the mark). - `parts()` lists an animated model's bones, `partOffset(name)` says where one sits, and `detachPart(name, velocity, spin, despawnTicks)` knocks it off. `detachedParts()` is saved on the chassis. - `showStatus(text)` borrows the vehicle's action-bar line for a moment. ### Building a vehicle the engine does not have A skateboard is pushed rather than throttled, tucks for speed and spins in the air. None of that is in the format, but the handle exposes the pieces: ```java Vehicle board = engine.vehicles().of(player).orElseThrow(); VehicleInput keys = board.input(); // what the driver is pressing, this tick if (keys.forward() && board.groundSpeed() < 7) { board.nudge(2.2); // a kick: +2.2 blocks/s along the heading board.dress(player, "myplugin_push"); // wear this emote over the seat's states } if (board.is(VehicleState.AIRBORNE) && keys.left()) board.spin(-360); board.undress(player); // back to the seat's own table board.dressVariant(player, "goofy"); // this rider's own variant of every state board.turnOccupant(player, 270.0); // face a different way from the seat; null resets board.holdOccupant(player, true); // sneak no longer dismounts while moving board.wallRiding(); // is it on a wall right now? ``` ```kotlin val board = engine.vehicles().of(player).orElseThrow() val keys = board.input() // what the driver is pressing, this tick if (keys.forward() && board.groundSpeed() < 7) { board.nudge(2.2) // a kick: +2.2 blocks/s along the heading board.dress(player, "myplugin_push") // wear this emote over the seat's states } if (board.`is`(VehicleState.AIRBORNE) && keys.left()) board.spin(-360.0) board.undress(player) // back to the seat's own table board.dressVariant(player, "goofy") // this rider's own variant of every state board.turnOccupant(player, 270.0) // face a different way from the seat; null resets board.holdOccupant(player, true) // sneak no longer dismounts while moving board.wallRiding() // is it on a wall right now? ``` - `input()` is the same input the physics read, on the same tick. Where keys can't be read (Spigot, or before 1.21.4) `keys()` is false and only `throttle()` means anything. Nothing in the engine acts on sprint, so it's yours to use. - `dressVariant` turns `moving` into `moving_goofy` and so on, falling back to the plain emote where no variant exists. - **Sneak is Minecraft's dismount.** Call `holdOccupant` once, when they get on: the dismount happens before your next tick task could react. A held rider can still get off by tapping sneak, and the hold stops applying once the vehicle is below half a block a second, so nobody is ever trapped. Tell riders what the key does now. ### A driver that isn't a player `drive(keys)` drives a vehicle as though somebody in the driver's seat were holding those keys, from the next tick until you call it again (RP Engine 0.2.51 and newer). Nobody has to be in it, and a real driver's keys are ignored meanwhile. It's for computer racers, demo laps and ghosts. The handling is a player's, `setEnabled(false)` still stops it, and `input()` reports your keys, so code that reacts to what the driver pressed works for this driver too. `drive(null)` hands it back. Steer and throttle run from -1 to 1 (steer: left to right); the space key is the handbrake, a jump or a climb, depending on the vehicle. ```java VehicleInput keys = new VehicleInput(true, 1.0, -0.4, // throttle 1, steer 0.4 to the left true, false, true, false, false, false, false); // forward, back, left, right, space, sprint, sneak kart.drive(keys); kart.carry(mannequin, 0); // somebody to see in the driver's seat ``` `carry(entity, seat)` sits a figure that isn't a player in a seat, a mannequin or an NPC. It's for show: it doesn't drive and it isn't an occupant. A seat is rebuilt when its chunk loads again, which drops it, so check `getVehicle()` and carry it again when it has come off. ### Moving the vehicle's own model `dress` is for the rider. `perform` plays one of the **model's** animations instead of whatever its `animations:` table says: ```java bike.perform("wheelie"); // the whole bike tips back about the rear axle // ... count your ticks ... bike.rest(); // back to the state table, wheels where they were ``` ```kotlin bike.perform("wheelie") // the whole bike tips back about the rear axle // ... count your ticks ... bike.rest() // back to the state table, wheels where they were ``` It works on a vehicle with no `animations:` at all. A performed animation loops until you call `rest()`, so you time the trick. It runs on real time even on a vehicle with [`animation-follows-speed`](/rp-engine/vehicles#a-wheel-should-turn-because-the-vehicle-moved), and the wheels pick up where they were afterwards. One animation plays at a time, so a trick that needs the wheels turning must turn them itself. Every vehicle handle method is main thread only. `ids`, `info` and `isRiding` are safe anywhere. ## Icons in your own text ```java String line = engine.icons().format(config.getString("welcome")); ``` ```kotlin val line = engine.icons().format(config.getString("welcome")) ``` Every `:namespace:id:` becomes its picture. An ID naming nothing is left exactly as written. **An animated icon is animated by you redrawing it.** Each frame is its own character, so `format` and `character` give the first frame, which is right for anything you send once. For text you send repeatedly, ask for the current frame: ```java // Once a tick, or as often as your scoreboard redraws. sidebar.setLine(0, engine.icons().formatNow(":mypack:loading: Loading")); engine.icons().characterNow(id).ifPresent(frame -> bar.setTitle(frame + " Boss")); ``` ```kotlin // Once a tick, or as often as your scoreboard redraws. sidebar.setLine(0, engine.icons().formatNow(":mypack:loading: Loading")) engine.icons().characterNow(id).ifPresent { frame -> bar.setTitle("$frame Boss") } ``` `IconInfo` has `frames()` (1 for a still), `animated()`, `fps()`, `loops()`, `frameAt(elapsedMillis)`, and `character(frame)` / `codepoint(frame)` for one frame (from 0). Redrawing once a tick shows every frame of anything up to 20 fps. A looping icon is timed from the epoch, a one-shot from server start. The PlaceholderAPI form `%rpengine_icon_%` is always the current frame. `IconInfo.aliases()` and `permission()` apply to players typing the icon in chat. `format` ignores both. ## Text Effects in your own text A [Text Effect](/rp-engine/text-effects) is a colour: text drawn in exactly that colour wears the effect, whatever sent it. So the API hands you the colour, and two ways to write text in it. ```java TextEffects effects = engine.textEffects(); // Tags in your own config, resolved the way RP Engine's own files are. player.sendMessage(effects.format(config.getString("welcome"))); // "Welcome to Skyblock!" // One effect by name: a content folder's before a Studio one. effects.find("fire").ifPresent(fire -> { meta.setDisplayName(effects.apply(fire.id(), "Flame Sword")); // Adventure, on Paper: the colour is all it takes. player.sendMessage(Component.text("Hot!", TextColor.color(fire.rgb()))); }); ``` ```kotlin val effects = engine.textEffects() // Tags in your own config, resolved the way RP Engine's own files are. player.sendMessage(effects.format(config.getString("welcome"))) // "Welcome to Skyblock!" // One effect by name: a content folder's before a Studio one. effects.find("fire").ifPresent { fire -> meta.setDisplayName(effects.apply(fire.id(), "Flame Sword")) // Adventure, on Paper: the colour is all it takes. player.sendMessage(Component.text("Hot!", TextColor.color(fire.rgb()))) } ``` | Method | What it does | |---|---| | `ids()` | Every Text Effect, both sources, sorted | | `info(id)` | A `TextEffectInfo`, by ID | | `find(name)` | By what somebody typed: `mypack:fire`, or a bare `fire` | | `apply(id, text)` | `text` in the effect, as a legacy string that resets after itself | | `format(text)` | Every `...` replaced. A tag naming nothing is left as written | `TextEffectInfo` has `id()`, `name()`, `color()` (`#rrggbb`), `rgb()`, `source()` (`CONTENT` or `STUDIO`) and `preset()`. `apply` and `format` write legacy codes (`§x§f§c...`), which every Spigot API takes. A colour code inside the text ends the effect; bold and italic do not. Safe from any thread. ## VFX A [VFX](/rp-engine/vfx) is a spell effect the engine plays in the world. Play one at a place, or on a player (at their feet, facing their way), and keep the handle if you want to end it early. ```java Vfx vfx = engine.vfx(); vfx.find("frost_nova").ifPresent(info -> { vfx.play(info.id(), player).ifPresent(play -> { // play.running() until it ends; play.stop() ends it now. }); }); ``` ```kotlin val vfx = engine.vfx() vfx.find("frost_nova").ifPresent { info -> vfx.play(info.id(), player).ifPresent { play -> // play.running() until it ends; play.stop() ends it now. } } ``` | Method | What it does | |---|---| | `ids()` | Every VFX, both sources, sorted | | `info(id)` | A `VfxInfo`, by ID | | `find(name)` | By what somebody typed: `mypack:frost`, or a bare `frost` | | `play(id, location)` | Plays it there, facing the location's yaw. Empty for an unknown ID, or below 1.21.4 | | `play(id, player)` | Plays it where the player stands, facing their way | | `play(id, location, caster, options)` | Plays it as a `VfxOptions` says (below); `caster` is whose placeholders a condition reads, and may be null | | `play(id, player, options)` | The same, cast on a player | | `playing()` | Every `VfxPlay` playing now | | `stop(tag)` / `stop(player)` | Ends the effects with that tag, or cast on that player, and says how many | | `stopAll()` | Ends them all, and says how many there were | `VfxOptions` is every [casting option](/rp-engine/vfx#casting-options): `loop()`, `loopFor(ticks)`, `loopTimes(n)`, `until(condition)`, `whileTrue(condition)`, `stopWhen(play -> ...)` (a check of your own, run every `checkEvery(ticks)`), `end(End.FINISH | End.CUT)`, `speed`, `scale`, `turn`, `offset(left, up, ahead)`, `follow(entity)`, `follow(vehicle)`, `delay`, `vary`, `seed`, `sounds`, `volume`, `viewers(Viewers.EVERYONE | Viewers.CASTER)` and `tag`. `follow(vehicle)` rides with a vehicle and turns with the way its body points, not with where its driver is looking, so an exhaust stays at the tail through a corner and an effect made in front of the caster plays in front of the vehicle. Cast it at `vehicle.location()`, which carries that heading: ```java vfx.play(boost, kart.location(), driver, VfxOptions.builder() .follow(kart) .build()); ``` ```java vfx.play(id, player, VfxOptions.builder() .loop() .stopWhen(play -> !combat.isFighting(player)) .follow(player) .tag("combat-aura") .build()); ``` `VfxInfo` has `id()`, `name()`, `durationTicks()`, `source()` (`CONTENT` or `STUDIO`) and `preset()`. A `VfxPlay` has `id()`, `location()`, `running()`, `stop()` (now), `finish()` (a loop plays out its fade), `options()`, `age()` and `passes()`. A Studio VFX is shown only to the players whose pack has it. Main thread only. ## Transitions A [Transition](/transitions) covers a player's whole screen, holds, and uncovers it. Studio's pack draws it and the engine only times it, so there is nothing to place and nothing to clean up. Run your code while the screen is covered: a teleport, a world load, a match starting. ```java Transitions transitions = engine.transitions(); ContentId arena = ContentId.parse("studio:arena").orElseThrow(); // In, then teleport while covered, then its own hold, then out. transitions.play(player, arena, () -> player.teleport(lobby)); // Held until you say so: a world loading, a match filling. transitions.cover(player, arena, () -> startLoading(player)) .ifPresent(play -> whenLoaded(play::release)); ``` ```kotlin val transitions = engine.transitions() val arena = ContentId.parse("studio:arena").orElseThrow() // In, then teleport while covered, then its own hold, then out. transitions.play(player, arena) { player.teleport(lobby) } // Held until you say so: a world loading, a match filling. transitions.cover(player, arena) { startLoading(player) } .ifPresent { play -> whenLoaded { play.release() } } ``` | Method | What it does | |---|---| | `ids()` | Every transition this server knows, as `studio:` | | `info(id)` / `find(name)` | A `TransitionInfo` (`name()`, `inTicks()`, `holdTicks()`, `outTicks()`, `soundIn()`, `soundOut()`), by ID or by what somebody typed | | `canPlay(player, id)` | Whether this player's pack holds the transition | | `play(player, id, whenCovered)` | In, the transition's own hold, out. `whenCovered` runs once the screen is fully covered | | `play(player, id, holdTicks, whenCovered)` | The same, holding for as long as you say | | `cover(player, id, whenCovered)` | In, then holds until you call `release()` | | `playing(player)` / `stop(player)` | The transition playing on a player, or end it now | Each play returns a `TransitionPlay`: `release()` starts the out now, `isCovered()` and `isFinished()` say where it is, and `cancel()` clears the screen at once. A play answers empty, and `whenCovered` never runs, for an unknown ID or for a player whose pack does not hold the transition: it is drawn by the pack it came in. A new play on a player replaces the one already playing on them, and a player leaving ends theirs quietly. Call these from any thread; `whenCovered` runs on the player's own thread (their region's, on Folia). ## Custom mobs The [custom mobs](/rp-engine/entities) a content folder's `entities/` declares and the ones a Studio sync carries (`studio:`) are one catalogue. ```java Mobs mobs = engine.mobs(); ContentId rhino = ContentId.parse("zoo:rhino").orElseThrow(); mobs.info(rhino).ifPresent(info -> info.animations()); // state -> animation name Entity spawned = mobs.spawn(location, rhino).orElseThrow(); mobs.spawn(location, rhino, 12); // at level 12; 0 rolls its own level: range mobs.idOf(entity); // which custom mob this is, if any mobs.isMob(entity); // is it a custom mob at all? mobs.level(entity); // its level, 1 unless spawned at another mobs.near(location, 24); // every custom mob in reach, nearest first mobs.state(entity); // what it is showing: MobState.WALK, ... mobs.play(entity, MobState.ATTACK); // as if it had happened: a one-shot, then back mobs.play(entity, "roar", 0); // any animation of its model, for its own length ItemStack egg = mobs.egg(rhino, 1).orElseThrow(); // hatches that mob where used ``` ```kotlin val mobs = engine.mobs() val rhino = ContentId.parse("zoo:rhino").orElseThrow() mobs.info(rhino).ifPresent { it.animations() } // state -> animation name val spawned = mobs.spawn(location, rhino).orElseThrow() mobs.spawn(location, rhino, 12) // at level 12; 0 rolls its own level: range mobs.idOf(entity) // which custom mob this is, if any mobs.isMob(entity) // is it a custom mob at all? mobs.level(entity) // its level, 1 unless spawned at another mobs.near(location, 24.0) // every custom mob in reach, nearest first mobs.state(entity) // what it is showing: MobState.WALK, ... mobs.play(entity, MobState.ATTACK) // as if it had happened: a one-shot, then back mobs.play(entity, "roar", 0.0) // any animation of its model, for its own length val egg = mobs.egg(rhino, 1).orElseThrow() // hatches that mob where used ``` **The states are `MobState`, and their order is their precedence**: `DEATH`, `SPAWN`, `ATTACK` and `HURT` play once, and only a higher one cuts them short; `RUN`, `WALK` and `IDLE` loop, and fall through to the next when the mob has no animation for them. `play(entity, state)` is refused (it returns false) when a higher one-shot is playing or the mob has nothing mapped for that state. `play(entity, name, seconds)` holds the stage for that long (0 for the animation's own length), then the mob goes back to what it is doing. `EntityInfo` also says how a mob looks after itself: `hurtFlash()`, `followRange()`, `glowing()`, `fireImmune()`, and three optional blocks: `bossBar()` (`color()`, `style()`, `range()`), `ranged()` (`projectile()`, `damage()`, `cooldown()`, `range()`) and `spawning()` (`worlds()`, `biomes()`, `replaces()`, `chance()`, light, time, group and `maxPerChunk()`). The builder takes each, so a mob you [register from code](#registering-content-from-code) can have them too. A projectile a custom mob fired carries the damage it was given. Setting a different damage on it in your own `EntityDamageByEntityEvent`, at a priority above `NORMAL`, wins. `MobSpawnEvent` fires before a custom mob spawns, however it came: an egg, a spawner, a command, `spawn`, or the engine's own natural spawning (`natural()` is true for that one). Cancel it for "none in the safe zone", or `setLevel` to change the level it comes at. The mob does not exist yet, so there is no entity on the event; it arrives a moment later in Bukkit's `CreatureSpawnEvent`, where `mobs.idOf` already names it. `spawn(…, level)`, `isMob`, `level`, `near` and the event need RP Engine 0.2.82 or newer. Listen for `MobStateChangeEvent` to follow what a mob is doing. It fires when what is *playing* changes, so a state the mob has no animation for never appears. `EntityDeathEvent` still hands you the drops list, after the mob's own `drops:` have replaced the vanilla loot. Everything here touches an entity, so it is main thread only, or on Folia the thread that owns the mob or the place. Needs RP Engine 0.2.51 or newer. ### Skills A custom mob's [skills](/rp-engine/skills) are MythicMobs' skill lines, and you extend the language the way MythicMobs' add-ons do: register a mechanic, a condition or a targeter by name, and every mob file can use it. Needs RP Engine 0.2.53 or newer. ```java MobSkills skills = engine.skills(); // - myplugin:smite{damage=6} @target ~onAttack 0.2 skills.registerMechanic("myplugin:smite", cast -> { cast.target().ifPresent(target -> { target.getWorld().strikeLightningEffect(target.getLocation()); if (target instanceof LivingEntity living) { living.damage(cast.number("damage", 4, "d") * cast.power(), cast.caster()); } }); return true; }, "smite"); // ?myplugin:inarena{name=pit} skills.registerCondition("myplugin:inarena", cast -> arenas.contains(cast.string("name", ""), cast.location())); // @myplugin:team{team=red} skills.registerTargeter("myplugin:team", new SkillTargeter() { @Override public Collection entities(SkillCast cast) { return new ArrayList<>(teams.members(cast.string("team", "red"))); } }); skills.cast(boss, "bosses:GroundSlam", player); // a metaskill, cooldown and conditions applying skills.stance(boss); // Optional skills.stance(boss, "enraged"); ``` ```kotlin val skills = engine.skills() // - myplugin:smite{damage=6} @target ~onAttack 0.2 skills.registerMechanic("myplugin:smite", { cast -> cast.target().ifPresent { target -> target.world.strikeLightningEffect(target.location) (target as? LivingEntity)?.damage(cast.number("damage", 4.0, "d") * cast.power(), cast.caster()) } true }, "smite") // ?myplugin:inarena{name=pit} skills.registerCondition("myplugin:inarena") { cast -> arenas.contains(cast.string("name", ""), cast.location()) } // @myplugin:team{team=red} skills.registerTargeter("myplugin:team", object : SkillTargeter { override fun entities(cast: SkillCast): Collection = ArrayList(teams.members(cast.string("team", "red"))) }) skills.cast(boss, "bosses:GroundSlam", player) // a metaskill, cooldown and conditions applying skills.stance(boss) // Optional skills.stance(boss, "enraged") ``` **`SkillCast` is what each one is handed**: `caster()`, `mob()`, `trigger()`, `target()` (the entity, when the target is one) and `location()` (always), `power()`, `stance()`, and the line's options by any of their names, with placeholders such as `` filled in and a range like `2to5` picked: `string`, `number`, `integer` and `bool`, plus `fill(text)` for text of your own. A mechanic is called once per target, on the caster's thread. A targeter's own options are read the same way; the shared ones (`limit`, `sort`, the offsets, `conditions`) are applied to what it returns. **Names are looked up when a line runs**, so registering in `onEnable`, after RP Engine has loaded its content, is in time. **Give yours a prefix** (`myplugin:smite`). A prefixed name nobody has registered yet is kept at load with a note that it "is not registered yet" and runs from the moment you register it, with no reload, where an unknown bare name is a typo and its line is skipped. Registering a name that already exists replaces it, RP Engine's own included. Names are case-insensitive. Listen for `MobSkillEvent` to see a skill before it runs, or cancel it; see [Events](#events). ## Events All in `ai.resourcepack.engine.api.event`, and cancellable unless the row says otherwise. | Event | When | |---|---| | `ContentLoadEvent` | Content finished loading and the packs are built. A reload replaces every definition, so rebuild anything you cached here. `cause()` is `STARTUP` or a reload. Not cancellable | | `PackSendEvent` | A pack went out to a player. `pack()` is the built pack; its `uuid()` is the id `PlayerResourcePackStatusEvent` reports on 1.20.3+, so you can match the two. Not cancellable | | `RigPackBuildEvent` | The emote rigs were rebaked: on every content load, or alone for a new skin or `reloadRigs()`. `alone()` and `separate()` say which. Not cancellable | | `ItemUseEvent` | A custom item was right- or left-clicked. `block()` and `face()` say what was clicked (null in the air). Cancelling cancels the vanilla use too | | `ModelPlaceEvent` | A model is about to be put down. `getPlayer()` is who is placing it, `model()` the model's id, `block()` the block it goes in (its location), and `stack()` the stack in their hand, so you can read what the item carries (null when a plugin placed it). Parking a vehicle from its item and hatching a custom mob from its egg fire it too, with the vehicle's or mob's id as `model()` | | `ModelPlacedEvent` | A model was put down and is standing. `placement()` is its handle and `stack()` the stack it came from, so you can copy what the item carries onto the placement's `data()`. Not cancellable | | `ModelBreakEvent` | A model is about to be broken. `model()`, `location()`, `player()` (null if nobody broke it), `hitbox()` (its Interaction entity, whose UUID tells two copies of one model apart) and `placement()`. Has a drop flag separate from cancelling | | `ModelInteractEvent` | A placed model was right-clicked, from your content folder or from Studio. Has `hitbox()`, `placement()` and `clickedPosition()`. Cancelling stops everything the engine would do with the click | | `ModelAnimationEvent` | A model is about to play an animation: `getPlacement()`, `getAnimation()`, `getCause()` and `getPlayer()` (who triggered it, if anyone) | | `ModelAnimationEndEvent` | One ended: finished, replaced or stopped. Not cancellable | | `ModelSeatEvent` | Somebody is about to sit on a chair, a seat bone or a vehicle seat. `placement()` or `vehicle()` says what it belongs to | | `ModelBindEvent` | A model is going on, or coming off, an entity that isn't ours (a boss, an NPC) | | `VehicleSpawnEvent` | A vehicle is about to be put down, by `/rp vehicle spawn` or a plugin's `spawn`. `id()`, `info()` and `location()`; there is no `Vehicle` yet. Cancelling means no vehicle. A parked one loading with its chunk doesn't fire it | | `VehicleRemoveEvent` | A vehicle is being removed for good, by `/rp vehicle remove` or `Vehicle.remove()`. Fires first, with its riders still seated and its `data()` readable. Not cancellable | | `VehicleEnterEvent` | Somebody is about to get into a vehicle. Fires after `ModelSeatEvent` for the same seat | | `VehicleExitEvent` | Somebody got out or was taken out, with the reason: dismounted, ejected, quit, reloaded, removed, unloaded, shutdown. After `RELOADED` they're put back a tick later with no enter event. Not cancellable | | `VehicleMoveEvent` | A vehicle is about to move (once per tick, only while moving). Cancelling stops it like a wall. Use it for regions, not fuel | | `VehicleStateEvent` | What a vehicle is doing changed: set off, stopped, took off, went under. Not cancellable | | `VehicleImpactEvent` | A vehicle hit another vehicle, the world, or the ground. See [Collisions and parts](#collisions-and-parts). Not cancellable | | `VehicleBailEvent` | A bad landing is about to throw a rider off. Cancelling keeps them aboard | | `MobSpawnEvent` | A custom mob is about to spawn: an egg, a spawner, a command, a plugin, or naturally (`natural()`). `id()`, `info()`, `location()`, and `level()` with `setLevel`. Cancelling means no mob | | `MobStateChangeEvent` | A custom mob's animation state changed: `previous()` and `state()`, null for its rest pose. Not cancellable | | `MobSkillEvent` | A custom mob is about to cast a skill: one of its own `skills:` lines (`skill()` is the line as written) or a metaskill (`skill()` is its id), with `trigger()` (`attack`, `timer`, `api` and so on) and `triggerEntity()`. Fires after the line's chance, health and conditions passed. Cancelling skips it and spends no cooldown | | `EntityDeathEvent` | A custom entity died. Says what it was, `killer()`, and `drops()`: Bukkit's live drop list, so editing it changes the loot. Not cancellable | | `PlayerLiquidEvent` | Somebody went into or came out of one of your liquids. Not cancellable | | `EmoteStartEvent` | An emote is about to start | | `EmoteEndEvent` | An emote ended, with the reason: finished, stopped, moved, damaged, quit, shutdown | | `EmoteRigSpawnEvent` | A rig's displays were spawned. Carries the new entity ids. Not cancellable | | `DialogOpenEvent` | A dialog is about to be put on a player's screen. `dialog()`, `values()`, and `followed()`: true when they reached it from the dialog they were in (a page, a move, a changed setting). Cancelling leaves their screen as it is | | `DialogClickEvent` | A player clicked something in a dialog that runs a command. `dialog()`, `values()` and `command()` (no leading slash). Cancelling stops the command running | | `DialogSlotMoveEvent` | A player is about to move a stack in a dialog's item slots. `dialog()`, `from()` and `to()` (slot keys like `inv/5`, `ender/3`, `api.bank/0`), `moving()` and `onto()` (the stack already there). The only dialog event: a button click runs a command instead, see [When a player clicks a button](#when-a-player-clicks-a-button) | **The engine decides whether something can physically happen, never whether it is allowed to.** Region protection, plot ownership and event worlds are rules about your server, and these events are where you enforce them. ```java @EventHandler public void onPlace(ModelPlaceEvent event) { if (!myRegions.mayBuild(event.getPlayer(), event.block())) { event.setCancelled(true); } } @EventHandler public void onLoad(ContentLoadEvent event) { menus.rebuild(); } ``` ```kotlin @EventHandler fun onPlace(event: ModelPlaceEvent) { if (!myRegions.mayBuild(event.player, event.block())) { event.isCancelled = true } } @EventHandler fun onLoad(event: ContentLoadEvent) { menus.rebuild() } ``` A plugin loading after RP Engine misses the first load The `STARTUP` event has already fired before your listener exists. Don't work around it with a delayed task: query the API in your own `onEnable`, and use the event for reloads after that. ### Priority The engine reads every one of these events after all handlers have run, so priority only orders you against other plugins. Listen at `NORMAL` unless you are deliberately arbitrating with another plugin, and treat `MONITOR` as read-only (a cancel there still counts). Vanilla's own events are different. The engine listens to those at `LOW` with `ignoreCancelled = true`, so cancelling a `PlayerInteractEvent` at `LOWEST` stops a custom item's use before RP Engine sees the click, which is usually what a protection plugin wants. ## Shipping content in your own jar An addon carries its models, items, vehicles and emotes as an ordinary [content folder](/rp-engine/content) inside its jar, under `resources/content//`, and installs it on enable: ```java try { if (AddonContent.install(this, engine, "skateboards")) { engine.reload(); // only when something actually changed } } catch (IOException e) { getLogger().severe("Could not install content: " + e.getMessage()); getServer().getPluginManager().disablePlugin(this); } ``` ```kotlin try { if (AddonContent.install(this, engine, "skateboards")) { engine.reload() // only when something actually changed } } catch (e: IOException) { logger.severe("Could not install content: ${e.message}") server.pluginManager.disablePlugin(this) } ``` It copies into `plugins/RPEngine/content//` and returns true only when something changed, so restarting on the same jar copies and reloads nothing. A reload rebuilds and resends every pack, so don't call it otherwise. A new build updates its own files and leaves everything else alone. If the server owner edited one of your shipped files, that edit survives the update: the console names the file and says to delete it to take the new version. Use your plugin's name as the namespace, and put RP Engine in `depend`. ## Registering content from code A plugin can add content directly instead of shipping a folder. Claim a namespace, define into the handle you get back, and the pack builder picks it up on the next build. ```java ClaimResult claim = engine.registration() .claim("myplugin", ContentSource.EMBEDDED); claim.namespace().ifPresent(ns -> { ns.define(ContentKind.ITEM, "ruby"); // ... and ns.release() when your plugin disables }); ``` ```kotlin val claim = engine.registration() .claim("myplugin", ContentSource.EMBEDDED) claim.namespace().ifPresent { ns -> ns.define(ContentKind.ITEM, "ruby") // ... and ns.release() when your plugin disables } ``` If the claim fails, `reason()` says why and `heldBy()` who has it. Holding `myplugin` can't define `otherpack:thing`, so two sources can't overwrite each other. `release()` drops the namespace and everything in it. Content from a plugin goes into the same registry under the same rules as a hand-written folder. ## Threading Reads about what the server holds (`ids`, `info`, all of `ContentRegistry`) are safe from any thread. Anything touching a player, an entity or a world is main thread only, and its javadoc says so. **On Folia there is no main thread**, so "main thread" means the thread that owns what the call touches: the player's or entity's own scheduler for anything about them (`player.getScheduler().run(...)`), and the region scheduler for anything at a place (`Bukkit.getRegionScheduler().run(plugin, location, ...)`), such as placing a model or playing a VFX at a spot. A call from the global region or another region's thread is the same mistake a call from an async thread is on Paper. Everything RP Engine does on its own already follows this, so your plugin only has to for the calls it makes. --- Source: https://resourcepack.ai/docs/rp-engine/armour # Armour Any item can be worn as armour, with your own art drawn on the player's body. There are two kinds: - **Flat armour**: a texture painted onto the player's body shape, like vanilla armour. Set up below. - **3D armour**: a set built from cubes that stands off the body (pauldrons, a tall crown). Made in [Studio](#3d-armour-from-studio) or [in Blockbench](#3d-armour-in-your-content-folder). ## Flat armour Add `armor:` to an [item](/rp-engine/items), saying which slot it goes in: ![Custom armour sets worn by a player](/images/armor.webp) ```yaml crown: material: GOLDEN_HELMET model: crown armor: head # head | chest | legs | feet ``` Ship one texture, at a path that depends on the slot: - `armor: legs`: `assets/textures/entity/equipment/humanoid_leggings/.png` - any other slot: `assets/textures/entity/equipment/humanoid/.png` Leggings use their own, narrower sheet in the game, so art drawn for the main sheet does not line up on legs. That is why each slot asks for exactly one texture. ### Using art from somewhere else `armor-art` takes a texture path under `assets/textures/` (or a resource location) and the build puts it at the right equipment path for you: ```yaml ruby_leggings: material: PAPER armor: legs armor-art: armour/ruby_layer_2 # assets/textures/armour/ruby_layer_2.png ``` An old-style armour layer sheet is exactly the picture the game wants: layer 1 for every slot except legs, layer 2 for legs. A file you put at the equipment path yourself wins over `armor-art`. This is how armour from [ItemsAdder](/rp-engine/itemsadder) and [Nexo or Oraxen](/rp-engine/nexo-oraxen) is worn without moving files. `armor-texture` names an equipment texture directly instead, including vanilla's: ```yaml crown: material: PAPER armor: head armor-texture: minecraft:gold # the game's own gold armour ``` `namespace:name` means the PNG at `assets//textures/entity/equipment//.png`. ### The model and the armour are separate `model:` is what the item looks like in a hand or a chest. `armor:` is what it looks like on a body. A crown can be a 3D model in your hand and a flat texture on your head; the game draws the two separately. An item with `armor:` and no `model:` looks like its vanilla material in the inventory and wears your art. Needs Minecraft 1.21.4 Custom armour art uses vanilla's equipment system, which arrived in 1.21.4. On an older server the item still works, the plugin says which case you are in at startup, and each build lists the armour that will look vanilla: - **below 1.21.2**, only materials that are already armour can be worn, so `armor:` on a stick does nothing; - **on 1.21.2 and 1.21.3**, any item can be worn but shows vanilla artwork. See [Minecraft versions](/rp-engine/versions). ## 3D armour from Studio Flat armour is a texture on the player's body shape. A [3D armour set from Studio](/armor#3d-armor) is built from cubes instead (pauldrons that stand off the shoulder, a crown taller than the head), and RP Engine puts it on the player. [Push the pack to your server](/testing/plugin) from Studio, then: ``` /rp armor # list the sets /rp armor wear studio:hazmat_suit [player] # put the whole set on /rp armor give studio:hazmat_suit [player] # or hand over the pieces /rp armor self # see your own pieces in F5 ``` The pieces are ordinary items. Wear them however you wear armour (shift-click, drag into a slot, a dispenser) and take them off the same way. ## 3D armour in your content folder You can also make a set yourself in Blockbench and put it in `armor3d/`: ```yaml # armor3d/costumes.yml santa: name: "Santa Suit" # optional; the ID when left out model: armor_santa # assets/models/armor_santa.bbmodel; the ID when left out displays: true # optional, default true; see below shaders: true # optional, default true; see below shader-helmet: false # optional, default false; see below ``` That is the set `mypack:santa`. The model is a `.bbmodel` project built on Blockbench's player template: feet at y = 0, 16 units to a block. It can face either way: front toward +Z with the right arm on the −X side, or front toward −Z with the left arm on the −X side (how the template and Bedrock armour templates stand). RP Engine works out which from where the arms and legs are. Put cubes in groups named after the bone they ride: | Group | Piece | |---|---| | `head` | Helmet | | `body`, `right_arm`, `left_arm` | Chestplate | | `waist`, `right_leg`, `left_leg` | Leggings | | `right_foot`, `left_foot` | Boots | A piece with no cubes is not part of the set, so a crown alone is a one-piece set. A group inside a bone (a `cape` inside `body`) rides that bone. A group with any other name is a load warning. Cubes and groups can be rotated any way you like. ### Armour points and durability Needs RP Engine 0.2.37 or newer. The pieces `/rp armor give` hands out only look like armour: they give no armour points. To make a 3D set protect its wearer, write the pieces as ordinary [items](/rp-engine/items) and add `armor3d:` with the set's id. The item keeps everything it already has (name, attributes, durability, recipes) and wears that set's piece for its `armor:` slot: ```yaml # items/void_armour.yml void_helmet: name: "&5Void Helmet" material: NETHERITE_HELMET armor: head armor3d: void_armour # the set; an id in this pack, or namespace:id durability: 1000 attributes: - armor: 5 ``` `armor:` is required with it, because it says which piece of the set the item is. `armor3d:` replaces `armor-art:`, so leave that out. ### Meshes and shader helmets Needs RP Engine 0.2.10 or newer. **Mesh elements** from Blockbench's mesh tool are read too, as quads and triangles. Triangulate any face with more than four corners, or it is left out with a warning. A mesh can be any shape (smooth surfaces, thin locks of fur), and a texel with alpha below 0.1 is cut out, so strands painted on a quad read as hair. Only the client's shaders can draw a mesh (see below), so: - A set with meshes wants `displays: false`. Viewers shown display entities see it without its meshes. - A mesh on the head needs `shader-helmet: true`. - Mesh faces are not nudged apart the way cube faces are, so keep two of them out of one plane. - Each bone costs one armour layer per four faces, drawn every frame. A few hundred faces per bone is a lot. **`shader-helmet: true`** hands the helmet to the shaders too, instead of the game drawing it as a head item. It can then be anything the body can (any turn, meshes), but a player on a version the shaders don't cover sees no helmet at all. ## How 3D armour is drawn - **The helmet** is drawn by the game, as an item on the head. It follows the head exactly, on every client. With `shader-helmet: true` the shaders draw it instead. - **On Minecraft 26.1 to 26.3**, the pack's shaders draw the rest of the set as part of the player's body, so it never lags and also shows on armour stands. RP Engine checks each viewer's version (through ViaVersion when it is installed) and spawns nothing extra for these players. - **Every other viewer** sees the body pieces as display entities, posed onto the player's limbs as they walk, swing, crouch and ride. A set with `displays: false` skips these, so other versions see only the helmet. Use that when your server only admits 26.1 to 26.3. If the pack stops loading when you add a set The shaders need a graphics card and driver with OpenGL 4.5 and subgroup support. A player whose computer lacks them (older integrated graphics, or a Mac) does not just miss the armour: Minecraft rejects the whole pack and shows "Resource reload failed". Add `shaders: false` to the set (RP Engine 0.2.45 or newer) and the pack carries no shader for it, so it loads for everybody and every player sees the display entities instead. Leave `displays` on when you do: with both turned off, nobody sees more of the set than the helmet. What to expect with display entities: - Swimming, crawling, gliding and sleeping hide the body pieces until you stand up again. - You do not see your own body pieces unless you turn on `/rp armor self`. - Anyone who cannot see you cannot see your armour either, so vanished staff stay vanished. - A set is roughly ten to forty entities per player wearing it. They are never saved and never collide with anything. Needs Minecraft 1.21.4 3D armour pieces are named with a string `custom_model_data`, which arrived in 1.21.4. On an older server the sets still load and are checked, nothing is built into the pack, and `/rp armor` says why. ## Why 3D armour lags behind Armour drawn by the pack's shaders is part of the player's body, so it cannot lag. If the body pieces trail behind a player, that player is being shown the display entities instead. The helmet gives it away: the game draws it, so it stays on the head while the rest trails. To see which one your own game gets, put the set on with `/rp armor wear ` while `/rp armor self` is off (it is off unless you turned it on). If RP Engine adds "Everyone else sees the whole set; you see the helmet", your game is being sent display entities. If the reply stops at "You're wearing ...", your game draws the set with the shaders. A player gets display entities when: - **The set has `shaders: false`.** Then every player does. It is usually added because the pack failed to load with "Resource reload failed" on an AMD graphics card on 26.3, which RP Engine 0.2.59 fixed. On 0.2.59 or newer, remove the line and check the pack still loads for your players. - **The player is not on Minecraft 26.1 to 26.3.** Older versions joining through ViaVersion, and any version newer than 26.3, always get display entities. - **The set cannot be drawn by the shaders.** The console says so when the content loads ("This set cannot be drawn by the client's own shaders"), with the reason. - **ViaVersion is only on your proxy.** RP Engine asks ViaVersion which version each player is on, and only sees it on the Minecraft server itself. Without it there, every player is taken to be on the server's version, so a player on another version can get the wrong one: a second suit trailing the one on their body, or no body pieces at all. Install ViaVersion on the server too. - **The Studio pack is from before 26.3 support.** A pack pushed or published before Studio supported 26.3 carries no shaders for it. Push or publish it again. - **RP Engine is out of date.** Before 0.2.44 there were no shaders for 26.3. Before 0.2.85, on Spigot without ViaVersion, every player got display entities, and a player whose game also draws the shaders saw two suits: one on the body and one trailing it. Update RP Engine. Display entities themselves trail when: - **You are watching your own armour** (`/rp armor self`, in F5). Your game moves your body the moment you press a key, and the server hears about it a ping later. RP Engine places your copy ahead of you by your ping, so it keeps up while you move steadily and is off for about one ping after you start, stop or turn. Other players do not see this: your body reaches them as late as the armour does. - **Your ping is high, or you move very fast.** RP Engine allows for at most 0.4 seconds of ping and never puts your copy more than 1.5 blocks ahead, so beyond that it falls behind. - **The server is lagging** (running below 20 TPS). The server moves the display entities every tick, so when ticks run late, the armour arrives late and in jumps. ## On Bedrock Flat armour reaches Bedrock players through [Geyser](/rp-engine/bedrock), drawn from the same equipment texture. 3D armour from Studio does too: the Bedrock pack carries each piece as a Bedrock worn model. RP Engine only recognises pieces it handed out itself, so a piece from a plain `/give` shows as paper on Bedrock until it is given again with `/rp armor give` or `/rp armor wear`. --- Source: https://resourcepack.ai/docs/rp-engine/bedrock # Bedrock and Geyser [Geyser](https://geysermc.org/) lets Bedrock Edition players (phones, consoles, Windows) join a Java server. When **Geyser-Spigot** runs on the same server, RP Engine builds a Bedrock pack (`.mcpack`) from your content every time it builds the Java pack, and sends it to Bedrock players as they join. They see your custom items with your art instead of the plain vanilla item underneath. There is nothing to configure. The console says what went into the pack: ``` [RPEngine] Bedrock pack built: 12 items, 3 models, 4 sounds, 6 icons, 2 armour pieces. ``` It is built from your default bundle (`default-bundle` in `config.yml`) and saved beside the Java zip in `plugins/RPEngine/output/`. ## What crosses over - **Items.** A Bedrock player sees the item with your art and its name. Bedrock draws every custom item as a flat icon, so a [3D item](/rp-engine/items#3d-items) or a piece of furniture uses its sprite if it has one at its `texture:` path, and otherwise a picture of its model, drawn the way the Java inventory shows it. An item with neither shows its base material's own icon. - **Armour**, on the body, from the item's equipment texture. The item needs no sprite of its own for this. - **Placed models.** Each piece is drawn for Bedrock players within 48 blocks as a native entity, at its size and facing, with its animations playing on their own client. A model that uses the game's own textures gets them baked in. The plugin downloads them once, in the background, the first time; a Bedrock player who joins in those first seconds sees a checkerboard on that model until they next join. - **Sounds.** A sound plays on Bedrock under the same id it plays under on Java, so actions and commands that play `mypack:laser` work for everyone. A file in `overrides/` that replaces a vanilla sound is added under the name Geyser plays that sound by, so it is heard on Bedrock too. - **Icons**, in chat and anywhere else text goes. Every icon is drawn about a line of text tall on Bedrock, whatever its height on Java. ## What does not **Emotes and vehicles.** Both are built from display entities, which Geyser does not draw. **Custom blocks.** A [custom block](/rp-engine/blocks) is a vanilla block in a state nothing else uses, and Bedrock players see that vanilla block. **Custom screens, HUD overlays and dialogs.** All three rely on Java-only font and dialog features. **A handful of vanilla sounds** that Bedrock plays itself rather than by name. Most vanilla sounds can be replaced on both editions. ## Custom mobs and bound models A [custom mob](/rp-engine/entities), and a model put on a mob with [`/rp bind`](/rp-engine/mobs) or MythicMobs' [`rpmodel`](/rp-engine/mythicmobs), is drawn for Bedrock players as its model (RP Engine 0.2.53 or newer). Geyser still moves, turns, hurts and kills the mob itself, so its hitbox is where its model is. What crosses: - the model, at its `scale:`, turned by its `turn:`, facing the way the mob faces; - its `idle`, `walk`, `attack` and `hurt` animations, played as the mob changes what it is doing, and anything a [skill](/rp-engine/skills) plays with `animate`; - the red flash when it is hurt, which is the Bedrock client's own; - a mob [synced from Studio](/mobs), drawn from the Bedrock pack Studio sends. What is different: - **A dying mob tips over** the way a Bedrock mob does, rather than playing its `death` animation. - **Its name sits over the hitbox**, where Geyser puts a name, not just above the model. - **Two mobs wearing one model share one `turn:`**: Bedrock uses the first mob's. - **`/rp bind` crosses only for a model Bedrock already has**: one a custom mob wears, or one with a [`place:`](/rp-engine/models) block. Any other item's model stays invisible to Bedrock players. Skills, drops, boss bars and the rest of a mob's behaviour run on the server, so they are the same for everybody. ## New items need a restart Geyser learns which Java items are custom **once, at startup**. `/rp reload` rebuilds the Bedrock pack and every Bedrock player gets the new art on their next join, but an item that did not exist at startup shows as its base material to Bedrock players until the server restarts. The console says so when it happens. The same goes for the very first start of a server whose items use the game's own textures (a model painted with oak planks, or an item falling back to its material's icon): those are downloaded once, after startup, and a restart puts their items in front of Bedrock players. After that they come from disk. ## A server without RP Engine Geyser alone can show a pack exported from Studio: **Export › Bedrock players on a Java server** gives the `.mcpack` and the item mappings Geyser reads. With RP Engine installed you don't need its mappings, and shouldn't add them: RP Engine registers the same items itself. See [Bedrock and Geyser](/bedrock). A Studio pack you dropped into `content/` as a `.zip` reaches Java players only. For Bedrock players, take `packs/` from that export and put it in Geyser's folder; RP Engine already knows the items. A pack that arrives by Sync or Distribution needs none of this. ## Studio models on Bedrock A pack pushed from Studio with `/rp sync` includes a Bedrock build whenever a player receiving it is on Bedrock, and a pack served through Studio's distribution always has one when anything in it can cross. A Bedrock client only accepts packs while joining, so the player is moved back onto the same server and given the pack on the way in. It takes a few seconds, and the sync survives it. Placed Studio models then show up for Bedrock players as native entities, drawn when a player comes within 48 blocks and taken away when they move off. Their animations play on the player's own client from the pack's keyframes, started by the same triggers as on Java. [3D armour](/rp-engine/armour#3d-armour-from-studio) from Studio is drawn on the body for Bedrock players too, when the pieces were handed out with `/rp armor give` or `/rp armor wear`. ## Designing for both If many of your players are on Bedrock, put anything they need to know in something that crosses over, such as an item's name and lore or chat. Bedrock players never see a menu that only exists as a custom screen, the HUD, a dialog, an emote, a vehicle or a custom block. --- Source: https://resourcepack.ai/docs/rp-engine/bettermodel # Moving from BetterModel If you used BetterModel, RP Engine can use your BetterModel files as they are, with no converting. Its **models** become items you can give, place and put on mobs, and its **player animations** become emotes. Copy the folder Copy `plugins/BetterModel/` into `plugins/RPEngine/content/` and name the copy `bettermodel`, in lower case. Restart or reload Restart the server, or run `/rp reload`. The console lists what loaded and anything it couldn't use. Try a model `/rp give bettermodel:knight` gives you the item for `models/knight.bbmodel`. ``` plugins/RPEngine/content/ bettermodel/ ← a copy of plugins/BetterModel/ models/knight.bbmodel → bettermodel:knight, an item wearing it players/steve.bbmodel → every animation in it, an emote: /emote roll players/dance.bbmodel → dance_ config.yml build/ ← ignored ``` The folder's name becomes the start of every ID in it (its [namespace](/rp-engine/ids)), which is why it must be lower case: a folder called `BetterModel` is refused, and the console says so. You don't need a `pack.yml` or any setting. `build/` is the resource pack BetterModel made from these files; RP Engine builds its own, so it skips that folder. ## Models become items `models/` holds blueprints exactly as [Model Engine](/rp-engine/modelengine)'s `blueprints/` does, and they load the same way. Each `.bbmodel` becomes an [item](/rp-engine/items) that wears it, named after the file, so `knight.bbmodel` is `bettermodel:knight`. A model in a subfolder is found where it is, and its ID is still the file's name. ``` /rp give bettermodel:knight the item that wears it /rp bind bettermodel:knight put it on the mob you are looking at ``` **The bone tags already mean the same thing.** BetterModel's are Model Engine's, and Model Engine's are RP Engine's: `h_` and `hi_` heads, `b_` and `ob_` hitboxes, `p_` seats and `tag_` nametags. See [Bones that do something](/rp-engine/bones). The generated item is a plain one, on paper. Write your own under the same ID in `items/` for anything more, a [`place:`](/rp-engine/models) block or a name, and yours wins. ## Player animations become emotes `players/` holds BetterModel's player animations: a `.bbmodel` of a player, whose animations it plays on somebody wearing their own skin. That is exactly an RP Engine [emote](/rp-engine/emotes), so each animation in each file becomes one, played with `/emote`. **The numbers carry over unchanged.** BetterModel's player rig faces the way the emote rig does and its keyframes mean what an emote's do. Its bone tags map to the emote bones: | BetterModel | Emote bone | |---|---| | `ph` | head | | `pc` · `pw` · `phip` (chest, waist, hip) | body | | `pra` · `prfa` | right arm · right forearm | | `pla` · `plfa` | left arm · left forearm | | `prl` · `prfl` | right leg · right shin | | `pll` · `plfl` | left leg · left shin | | `player_root` | the whole figure | **Emote names are shared by the whole server**, so an animation in BetterModel's own `steve.bbmodel` is named after the animation alone (`/emote roll`), and one in any other file is prefixed with that file's name (`/emote dance_spin`). Two things differ, and the load says so **Their torso is three bones and ours is one.** BetterModel has a hip, a waist and a chest; the emote rig has a body. Where more than one of them moves, the most specific (the chest, then the waist, then the hip) is the body. **Their arms and head ride the torso; ours stand on their own.** A bow from the waist bends the body here without carrying the arms and head down with it. An animation that leans on that will want its arms and head keyframed to follow. Held-item and cape bones are not carried, and nor is Molang in a keyframe, which has nothing here to evaluate it and is read as zero. Emotes play on a rig baked from each player's skin, which needs Minecraft 1.21.4 or newer. On an older server they still load, but play on nobody. See [the rig it plays on](/rp-engine/emotes#the-rig-is-not-the-animation). --- Source: https://resourcepack.ai/docs/rp-engine/blocks # Custom blocks A custom block is a real block players place, mine and stand on: an ore, a machine, a crate, a flower, a set of stairs. For decoration that does not need to be mined or walked on, a [placed model](/rp-engine/models) is usually the better choice (see [the end of this page](#what-it-really-is)). Blocks go in YAML files in the `blocks/` folder of your pack inside `plugins/RPEngine/content/` (your [content folder](/rp-engine/content)), with their models in `assets/models/`. ![Custom blocks](/images/blocks.webp) ```yaml # blocks/ores.yml ruby_ore: base: note_block # note_block | mushroom_stem | tripwire (a plant) model: ruby_ore # assets/models/ruby_ore.bbmodel hardness: 3.0 # stone is 1.5 tool: pickaxe # what has to be held for the drop drop: mypack:ruby # default: itself light: 0 # 0-15, what it gives off sound: minecraft:block.stone.place ``` Every block comes with an item that places it, with nothing extra to declare. `/rp give mypack:ruby_ore` gives you one. | Field | What it does | |---|---| | `base` | Which vanilla block it is made from. `note_block` (49 available), `mushroom_stem` (63) or `tripwire` (a [plant](#plants)) | | `model` | A `.bbmodel` or Java model under `assets/models/` | | `hardness` | How long it takes to break. Stone is `1.5`, dirt `0.5`, `0` is instant | | `tool` | `pickaxe`, `axe`, `shovel`, `hoe` or `sword`. Leave it out for anything | | `drop` | A content ID. Defaults to the block itself | | `light` | 0-15. See [Light](#light) | | `sound` | Played over the base block's own sound, on place and break | | `name`, `lore` | For the item that places it, as on an [item](/rp-engine/items). Without them it has the base block's name | | `actions` | What it does when placed, right-clicked or mined, as on an [item](/rp-engine/actions#the-thing-in-the-world) | RP Engine handles breaking itself, with the crack animation, so `hardness` and `tool` work as they would on a vanilla block. With the wrong tool the block still breaks but drops nothing, like stone with a shovel. ## Light `light:` makes a block glow. The engine places a real light block in an empty space beside it (above it where it can) and removes it when the block is broken or blown up. It only ever removes a light it placed. The glow is one level dimmer on the far side than a vanilla lamp's. For a block that lights up when powered by redstone, use [`shape: bulb`](#stairs-slabs-doors-and-other-shapes). No sound of its own A custom block keeps its base block's sounds. `sound:` plays yours over the top rather than replacing them. ## Turning, and states A block can face the player, lie along an axis, or have several states, each drawn its own way: ```yaml kiln: model: kiln rotate: horizontal # horizontal (a furnace) | all (a dispenser) | axis (a log) safe: model: safe properties: facing: facing # facing | facing-all | axis | boolean | a list of values open: boolean appearances: # a state, or part of one, and the model it wears "open=true": safe_open "facing=east": { y: 90 } # the block's own model, turned "facing=east,open=true": { model: safe_open, y: 90 } click: open # a right-click turns this property to its next value ``` `rotate:` is the short form. It turns the one model the way the game turns a furnace, a dispenser or a log, so draw the model facing north. The long form lists `properties:` and gives `appearances:` for them. The most specific appearance that matches a state wins, and a state no appearance matches uses the block's own model. `facing`, `facing-all` and `axis` are set when the block is placed (facing the player, or along the face it was placed against). Every other property starts at its first value and changes through `click:`, [growing](#growing), or an action. Every state uses up the pool A block facing four ways uses four of the 49; one that also opens uses eight. `/rp blocks` shows how many are left. Adding a property to an existing block later keeps the blocks already in your world unchanged. `random:` picks one look each time a block is placed, the way vanilla varies flowers: ```yaml cobbles: random: - cobbles_a - { model: cobbles_a, y: 90 } - cobbles_b ``` ## Plants `base: tripwire` (or `plant`) makes a block like string: no collision, broken at a touch. That suits a flower, a fern or a pebble. ```yaml daisy: base: plant model: daisy # usually a cross model: parent minecraft:block/cross ``` Only tripwire in a state normal string never uses is taken, so tripwire traps still look normal. Two plants, or thirty-two, depending on Paper On a normal server only **two** custom plants fit, because tripwire changes its state to match the string beside it. On Paper, set `block-updates.disable-tripwire-updates: true` in `config/paper-global.yml` and **thirty-two** fit. Nexo, Oraxen and ItemsAdder ask for the same setting. RP Engine reads Paper's setting at start. `blocks.tripwire-frozen` in [`config.yml`](/rp-engine/config) (default `auto`) overrides it if your Paper config is somewhere else. Setting it to `true` when tripwire is not frozen makes neighbouring plants turn into each other. ## Growing A crop is a plant with stages: ```yaml tomato: base: plant stages: [tomato_0, tomato_1, tomato_2] # an age property, one model per stage grow: every: 2m # about this long per stage (30s, 5m, 600t) light: 9 # the least light it grows in bone-meal: true # bone meal moves it a stage ``` `grow:` moves a property (`age`, or the one named by `property:`) to its next value until the last. Each stage is a state, so a three-stage crop uses three of the pool. Growth survives a restart, and only loaded chunks grow, as in vanilla. ## Stairs, slabs, doors and other shapes A note block is always a full cube to the game. For other shapes, a custom block takes over a whole kind of vanilla block, and the game handles everything that kind does: ```yaml ruby_stairs: shape: stairs # stairs | slab | door | trapdoor | grate | bulb texture: block/ruby # every face; or textures: { top, bottom, side } oak_gate: shape: door textures: { top: block/gate_top, bottom: block/gate_bottom } item-texture: item/gate # a door's item is a flat picture ``` The parts are made from your textures the way the game makes its own: a stair's straight run and both corners, a door's eight halves. So a stair joins its neighbours into corners, a slab stacks into a double slab, and a door opens by hand and by redstone. To draw the parts yourself, name a model for each with `models: { straight: ..., inner: ..., outer: ... }` instead. | Shape | What it is | Parts | |---|---|---| | `stairs` | A stair | `straight`, `inner`, `outer` | | `slab` | A slab, and two of them stacked | `bottom`, `top`, `double` | | `door` | A two-high door | `bottom_left`, `bottom_left_open`, `bottom_right`, ... `top_right_open` | | `trapdoor` | A trapdoor | `bottom`, `top`, `open` | | `grate` | A solid block you can see through: leaves, glass | `block` | | `bulb` | A block that lights up when redstone switches it | `off`, `on` | ### What a shape costs Each custom shape uses up one kind of vanilla block. RP Engine takes waxed copper blocks, because they never change on their own and are rarely built with (Oraxen and CraftEngine use the same ones). Slabs also take the petrified oak slab, which survival players cannot get. So each shape has room for **four** custom blocks (five for slabs), taken in the order weathered, exposed, oxidized, then fresh copper. Doors, trapdoors, grates and bulbs need Minecraft 1.21, where copper versions of them were added. Bulbs are taken brightest first, and a bulb's light level is its copper's: 15, 12, 8, then 4. Players' own waxed copper keeps working When a player places a waxed copper block of a kind that was taken, it goes down as the unwaxed version (which looks the same), is marked so it never ages, and gives back the waxed item when broken. Honeycomb and axes work as usual, and waxed copper in newly generated chunks (trial chambers) is handled the same way. Waxed copper of that kind already in your world before it was taken shows the custom look instead, because nothing can tell it apart. `base: minecraft:spruce_stairs` takes a kind you choose. Every spruce stair on the server becomes yours, so pick one nobody uses. ## What else a block does ```yaml palm_log: rotate: axis strip: { into: stripped_palm_log, drop: bark } # what an axe makes of it lamp_off: click-into: lamp_on # a right-click turns it into another block ash: falls: true # falls like sand vault_door: blast-resistant: true # explosions leave it standing crate: storage: { type: chest, rows: 3, title: Crate } # as a placed model's ``` `storage:` takes the same types as a placed model (see [Working furniture](/rp-engine/furniture#storage)). Breaking the block or blowing it up spills what is inside; a `shulker` keeps it inside the item instead. An explosion drops the custom block, not the note block underneath, and pistons will not push a custom door or plant. ## What it really is The game cannot add new blocks, so a custom block is a vanilla block in a state nothing else uses, showing your model. Every custom-block plugin works this way, and it has some costs worth knowing before you design a hundred. Back up blocks.json `plugins/RPEngine/blocks.json` records which block state is which custom block. If you lose it, **every custom block on the server turns into a different one**, and no reload fixes it. IDs are added in the order they are first seen and never renumbered, so adding or removing a pack does not change blocks already placed. - **The pool is small: 49 note blocks, 63 mushroom stems.** A note block changes its instrument to match the block beneath it, and nothing can stop that, so only the note and powered states can tell custom blocks apart. `/rp blocks` shows how many are left. - **Note blocks are taken over.** On a server with note-block custom blocks, a plain note block still looks normal, but a custom one does not play a note. Nothing in vanilla ever changes a mushroom stem, so `mushroom_stem` is the better base when you do not need the larger pool. Furniture still wants a placed model A [placed model](/rp-engine/models) has no pool, no limit and no mapping to lose, and can be any shape. Use a custom block for what a model cannot be: something you mine, something that holds you up, something a piston should not move. ## Moving a world from another plugin Pack definitions come across from [ItemsAdder](/rp-engine/itemsadder), [Nexo and Oraxen](/rp-engine/nexo-oraxen) and [CraftEngine](/rp-engine/craftengine) automatically. Blocks already placed in a world mostly do not: each plugin numbers its note-block, mushroom and tripwire states its own way, so those blocks show as whatever RP Engine gave that state. Furniture placed by another plugin is that plugin's own entities. Both have to be rebuilt or remapped by hand. **Shapes are the exception.** Oraxen's stairs, slabs, doors, trapdoors, grates and bulbs, and CraftEngine's stairs, slabs, doors and trapdoors, keep the same vanilla block kind when imported, so the ones already in your world carry on working. --- Source: https://resourcepack.ai/docs/rp-engine/bones # Bones that do something In Blockbench, a model's parts are grouped into bones (the folders in the outliner). Start a bone's name with one of these prefixes and it does more than get drawn: a head that looks at its target, a wing you can hit, a seat. They are the same prefixes Model Engine uses, so a rig you already have, or bought, works without renaming anything. | Bone name | What it does | |---|---| | `h_head` | Turns to look at whatever its mob is targeting | | `hi_head` | The same, and every bone under it turns with it | | `b_wing` | A hitbox of its own, so the model is hit where you aimed | | `ob_wing` | The same, and the hitbox turns with the bone | | `p_seat1` | A passenger seat. Right-click it to sit | | `mount` | Where the driver sits. One per model | | `tag_name` | Where a name floats | Heads and seats only work on a [model worn by a mob](/rp-engine/mobs) or a [custom entity](/rp-engine/entities): a placed statue has nothing to look with and nobody to carry. Any other bone is an ordinary bone, which is nearly all of them. A model needs none of these. ## Heads An `h_` or `hi_` bone turns toward what its mob is fighting, on top of whatever the animation is doing, so a walk cycle still moves the head. It follows the target, not the gaze The server cannot read which way a mob's head is turned, only its body. So a head bone looks at the mob's current target, and faces straight ahead when it has none. ## Hitboxes `b_` and `ob_` give a bone a hitbox of its own, so a dragon is hit on the wing you aimed at instead of inside one box round the whole animal. The hitbox is sized from the bone and follows the animation. Use `ob_` for bones that rotate a long way, so the hitbox turns with them. A hit on a bone is passed on to the mob. The wing has no health of its own: the mob takes the damage with its own armour, death and loot. You can make some bones count for more or less: ```yaml place: hitboxes: head: 2.0 wing: 0.5 ``` Each number multiplies the damage of a hit on that bone. It matches the bone's own name only, not the bones inside it, so a head inside a torso still counts as a head. (An [animation mask](/rp-engine/animation#masks) works the other way and includes everything under the bone.) ## Seats `p_` bones are passenger seats and `mount` is the driver's. Right-click one to sit; the seat follows the bone, so a seat on a walking mount moves with it. `mount` must be the whole bone name. A bone called `mountain` is scenery. ## Nametags `tag_` marks where a name floats. Vanilla puts a name a fixed distance above the hitbox, which on a large model can be somewhere inside its knee. The text is the mob's own custom name, and its normal name tag is hidden while the model is on so there are not two. Taking the model off brings it back. ## Not supported Procedural bones (tails, chains of segments) and bones that hold an item are not supported. --- Source: https://resourcepack.ai/docs/rp-engine/bundles # Bundles A **bundle** is one resource pack RP Engine builds from your content folder. Most servers have one, called `main`, and never need to think about it: every content pack goes into `main` unless it says otherwise, and every joining player is sent `main`. `/rp bundles` lists the bundles with their sizes, hashes and the link each one is served at. ## Choosing which bundle a pack goes into ```yaml # in a pack's pack.yml bundles: [main] ``` A content pack lists the bundles it belongs to (`main` if it says nothing), and a bundle can hold many packs. One pack can be in several bundles, which is how a shared base pack gets into each of them without being copied. ## Which bundle players get ```yaml # in config.yml default-bundle: main # what every joining player is sent; empty sends nothing ``` Every player is sent the default bundle. Other bundles are still built (into `output/`) and served, so you can hand their link to another plugin, but RP Engine has no command or API that sends a player a different one. On top of the default bundle, a player can be sent small extra packs: their [emote rigs](/rp-engine/config#emotes), and a pack they are testing from Studio with [`/rp sync`](/rp-engine/commands#studio). From Minecraft 1.20.3 these are stacked on the bundle. Below 1.20.3 a player holds one pack at a time, so the last one sent is the one they have. Set `default-bundle: ""` if another plugin sends your players their resource pack and you only want RP Engine to build it. ## Rebuilding changes nothing unless the content did The same content always builds to exactly the same zip. The game recognises a pack it already has by its hash, so a restart or a reload that changes nothing makes nobody download anything. ## Serving them By default each bundle is uploaded to ResourcePack AI's free pack host and players are sent the link to it, so there is nothing to open or configure. RP Engine can serve them from your own server instead, on the game port or a port of its own, or leave hosting to you. See [Serving the pack](/rp-engine/config#serving-the-pack). --- Source: https://resourcepack.ai/docs/rp-engine/citizens # Citizens With Citizens installed, an NPC can wear one of your [models](/rp-engine/models) and keep it through a chunk unloading, a respawn, `/npc reload` and a server restart. Look at the NPC and run: ``` /rp bind mypack:shopkeeper ``` There is no trait to add by hand and nothing to configure. `/rp unbind`, looking at the NPC, takes the model off for good. Player-shaped NPCs need the .others node Most Citizens NPCs are player entities, so binding one counts as putting a model on another player and needs `rpengine.bind.others` (and `rpengine.unbind.others` to take it off) as well as `rpengine.bind`. Ops have both. See [Permissions](/rp-engine/permissions#pointing-a-command-at-somebody-else). ## What the NPC keeps Everything: its skin, name, pathing, commands, traits and identity. RP Engine hides the normal body and shows the model instead; take the model off and the NPC is exactly what it was. Binding adds an `rpmodel` trait to the NPC, which Citizens saves, and that is how the model comes back after every respawn. ## Animating one From your own plugin, through the [API](/rp-engine/api): ```java models.animate(npc.getEntity(), "wave"); ``` Citizens has no skill system to trigger animations from, so deciding when an NPC waves is up to your plugin. --- Source: https://resourcepack.ai/docs/rp-engine/commands # Commands RP Engine has one main command, `/rpengine`, which you can also type as `/rpe` or `/rp`. Players also get `/emote`, and `/emotereply` for answering emote invitations. `/rp` on its own (or `/rp help`) lists the commands you are allowed to run. Arguments tab-complete, and you are only offered subcommands you have permission for. When the plugin tells you to run a command in chat, you can click it. `[player]` means the command can target somebody else, which needs a second permission. See [Pointing a command at somebody else](/rp-engine/permissions#pointing-a-command-at-somebody-else). ## Content | Command | What it does | Permission | |---|---|---| | `/rp reload` | Reread the content folder and config, and rebuild every pack | `rpengine.reload` | | `/rp info` | How much content is loaded, and the commands you can run | `rpengine.info` | | `/rp bundles` | The built packs, with their sizes and hashes | `rpengine.bundles` | | `/rp push` | Send this server's pack to yourself again | `rpengine.push` | | `/rp items` | Every custom item | `rpengine.items` | | `/rp item menu` | A chest of every custom item: click for one, shift-click for a stack | `rpengine.item` | | `/rp give [amount]` | Give yourself an item | `rpengine.give` | | `/rp blocks` | Every custom block, and how many block states are left | `rpengine.blocks` | | `/rp recipes` | Every recipe | `rpengine.recipes` | ## Models and entities | Command | What it does | Permission | |---|---|---| | `/rp models [radius]` | Placed models near you, with orphans marked | `rpengine.models` | | `/rp purge [radius]` | Remove orphaned models near you (see [Reloading](/rp-engine/reloading#orphans)) | `rpengine.purge` | | `/rp entities` | Every custom entity | `rpengine.entities` | | `/rp spawn ` | Spawn a [custom mob](/rp-engine/entities#spawning-one) where you stand | `rpengine.spawn` | | `/rp spawn [world] [count] [level]` | Spawn up to 64 at a place, at a level. The world may also come first. This is the form the console uses | `rpengine.spawn` | | `/rp egg [player] [amount]` | A spawn egg that hatches that mob where it is used | `rpengine.egg` | | `/rp spawner create [x y z [world]]` | Make a [spawner](/rp-engine/drops-and-spawners#spawners), where you stand if you give no place | `rpengine.spawner.create` | | `/rp spawner set ` | Change one of a spawner's settings | `rpengine.spawner.set` | | `/rp spawner remove ` | Remove a spawner made in game. Its mobs stay | `rpengine.spawner.remove` | | `/rp spawner list` | Every spawner | `rpengine.spawner.list` | | `/rp spawner info ` | One spawner's settings | `rpengine.spawner.info` | | `/rp bind ` | Put that item's model on the mob you are looking at | `rpengine.bind` | | `/rp unbind` | Take it off again | `rpengine.unbind` | The radius is in blocks: 16 by default, 128 at most. Binding a model to another player, rather than a mob, needs `rpengine.bind.others`. Giving an egg to somebody else needs `rpengine.egg.others`, and `rpengine.spawner` grants every `/rp spawner` verb. ## Sound, text and interface | Command | What it does | Permission | |---|---|---| | `/rp sounds` | Every custom sound | `rpengine.sounds` | | `/rp sound [player]` | Play one | `rpengine.sound` | | `/rp sound stop [player]` | Stop one early, or every custom sound | `rpengine.sound` | | `/rp music` | Every piece of [music](/rp-engine/music), and what is playing for you | `rpengine.music` | | `/rp music play [player]` | Start a piece | `rpengine.music.play` | | `/rp music stop [player]` | Stop it | `rpengine.music.stop` | | `/rp music skip [player]` | On to the next track | `rpengine.music.skip` | | `/rp icons` | Every icon, with the character it became | `rpengine.icons` | | `/rp say ` | Send yourself text, with `:pack:icon:` drawn as icons and `` as [Text Effects](/rp-engine/text-effects) | `rpengine.say` | | `/rp effects` | Every Text Effect, each drawn in itself, with its colour | `rpengine.effects` | | `/rp effects presets` | The ready-made Text Effects a content file can name | `rpengine.effects` | | `/rp effect [text]` | Send yourself text in a Text Effect | `rpengine.effect` | | `/rp vfx` | Every [VFX](/rp-engine/vfx) this server can play | `rpengine.vfx` | | `/rp vfx presets` | The ready-made VFX a content file can name | `rpengine.vfx` | | `/rp cast [player] [options]` | Play a VFX where a player stands: on a loop, until a condition, faster, bigger, following them ([options](/rp-engine/vfx#casting-options)) | `rpengine.cast` | | `/rp cast at [world] [options]` | Play a VFX at a place, tied to no player: `~` counts from whoever runs it ([casting at a place](/rp-engine/vfx#casting-at-a-place)) | `rpengine.cast.at` | | `/rp cast stop [all\|\|tag:]` | End VFX playing: all, one player's, or one tag's | `rpengine.cast` | | `/rp transitions` | Every [Transition](/transitions) this server can play | `rpengine.transitions` | | `/rp transition [player\|@a] [hold ticks]` | Cover a screen with a transition, hold it, then uncover it. Without a hold, it holds for the transition's own | `rpengine.transition` | | `/rp screens` | Every screen and HUD | `rpengine.screens` | | `/rp screen [player]` | Open a screen | `rpengine.screen` | | `/rp hud [player]` | Draw an overlay, or clear it | `rpengine.hud` | | `/rp shaders` | Every [shader object](/shaders) from Studio, and whether you hold its pack | `rpengine.shaders` | | `/rp shader [player]` | Show a shader object, or take them all off | `rpengine.shader` | ## Dialogs Dialogs need Minecraft 1.21.6 or newer. | Command | What it does | Permission | |---|---|---| | `/rp dialogs` | Every [dialog](/dialogs), and whether you hold its pack | `rpengine.dialogs` | | `/rp dialog [name=value...] [player]` | Open one, filling its `{placeholders}` with the values given | `rpengine.dialog` | | `/rp var ` | Change one of your own dialog settings | `rpengine.var` (everyone) | | `/rp page ` | Turn the dialog you are looking at to another page | `rpengine.page` (everyone) | | `/rp page close` | Close the dialog you are looking at | `rpengine.page` (everyone) | | `/rp slot ` | Move an item in a dialog's item slots | `rpengine.slot` (everyone) | | `/rp click ` | Press a dialog's console button: what a `console:` button runs | `rpengine.click` (everyone) | | `/rp run ` | Press a dialog's button of several commands: what a `command:` list runs | `rpengine.run` (everyone) | | `/rp quick ` | Open a dialog on the [Quick Actions key](/dialogs#the-quick-actions-key): what its launcher's button runs | `rpengine.quick` (everyone) | | `/ [player]` | A dialog's own command, such as `/shop` | everyone, or the permission the dialog names | `var`, `page`, `slot`, `click`, `run` and `quick` are what clicks inside a dialog run, so every player has them, and they are not tab-completed. Each only does what a click in the dialog you were shown could do. A dialog gets its own command from `command:` in its file, or **Players open it with** in Studio. If another plugin already has that command name, the other plugin keeps it. `/rp dialogs` shows each dialog's command. ## Emotes | Command | What it does | Permission | |---|---|---| | `/emote` | List the emotes you can play | `rpengine.emote` (everyone) | | `/emote ` | Perform an emote, or wear it if it is a movement set | `rpengine.emote` (everyone) | | `/emote ` | Perform it with other players. They are asked first | `rpengine.emote.cast` | | `/emote --showYourself` | Wear a movement set and see it yourself. For testing: it lags behind you | `rpengine.emote` | | `/emote stop` | Stop yours, and everybody in it with you | `rpengine.emote` | | `/emotereply ` | Answer an invitation. This is what the **[accept]** and **[deny]** buttons run | none | | `/rp emote ...` | The same as `/emote` | `rpengine.emote` | | `/rp emotes` | Every emote the server holds | `rpengine.emotes` (everyone) | `emotes.player-commands: false` in [`config.yml`](/rp-engine/config#emotes) removes `/emote`, for a server that already has one from another plugin. `/rp emote` still works, and `/emotereply` is always there. ## Liquids | Command | What it does | Permission | |---|---|---| | `/rp liquid corner` | Mark one corner of a pool | `rpengine.liquid` | | `/rp liquid fill ` | Fill the box between that corner and where you stand with that liquid | `rpengine.liquid` | | `/rp liquid clear` | Remove the pool you are in | `rpengine.liquid` | | `/rp liquid list` | Every pool, per world | `rpengine.liquid` | ## Vehicles | Command | What it does | Permission | |---|---|---| | `/rp vehicles` | Every vehicle, and who fits in it | `rpengine.vehicles` | | `/rp vehicle ` | Park one where you stand, facing the way you face | `rpengine.vehicle` | | `/rp vehicle remove` | Take away the one nearest you | `rpengine.vehicle` | Players get in by right-clicking a seat. See [Vehicles](/rp-engine/vehicles). ## 3D objects 3D objects need Minecraft 1.21.4 or newer. Every verb except `spawn` acts on the nearest object, and each has its own node, `rpengine.object.`. | Command | What it does | Permission | |---|---|---| | `/rp objects` | Every [3D object](/rp-engine/objects), with its states and sequences | `rpengine.objects` | | `/rp object spawn [size] [x y z]` | Put one down in front of you, or at those coordinates | `rpengine.object.spawn` | | `/rp object state `, `replay` | Put it into a state, or play its state again | `rpengine.object.state`, `.replay` | | `/rp object play `, `stop` | Run or stop one of its sequences | `rpengine.object.play`, `.stop` | | `/rp object move`, `turn`, `size`, `seed` | Move, turn or resize it, or change its seed | `rpengine.object.move`, `.turn`, `.size`, `.seed` | | `/rp object remove [all]` | Take it away, or every one | `rpengine.object.remove` | `rpengine.object` grants every verb. See [3D objects](/rp-engine/objects#commands) for the arguments. ## 3D armour | Command | What it does | Permission | |---|---|---| | `/rp armor` | Every 3D armour set the server holds | `rpengine.armor` | | `/rp armor wear [player]` | Put the whole set on. What they were wearing goes into their inventory | `rpengine.armor` | | `/rp armor give [player]` | Hand over its pieces | `rpengine.armor` | | `/rp armor self` | See your own 3D armour, in F5 and first person. Run it again to hide it | `rpengine.armor` | See [Armour](/rp-engine/armour#3d-armour-from-studio). ## Studio **Sync** sends a pack open in Studio to you (and anybody you add) for testing, on top of the server's own pack. Nobody else sees it and nothing on the server changes. **Distribute** serves a published pack to every player. See [Testing with the plugin](/testing/plugin) and [Distribution](/distribution). | Command | What it does | Permission | |---|---|---| | `/rp sync ` | Pair with a pack open in Studio, using the code from Studio | `rpengine.sync` | | `/rp sync add ` | Share your pushes with somebody else | `rpengine.sync` | | `/rp sync accept` / `deny` | Answer an invitation to somebody's sync | `rpengine.sync` | | `/rp sync who` | Who is on your sync | `rpengine.sync` | | `/rp sync remove ` | Take somebody off, and the pack off them | `rpengine.sync` | | `/rp sync leave` | Leave somebody else's sync | `rpengine.sync` | | `/rp sync stop` | End yours, for everybody on it | `rpengine.sync` | | `/rp distribute ` | Serve a pack published in Studio to everybody who joins, using the code from the pack's Distribution page. It is kept in `content/studio-/` and updated on every release | `rpengine.distribute` | | `/rp distribute off` | Stop serving it, and remove its folder | `rpengine.distribute` | | `/rp distribute off --keep` | Stop serving it, and keep its folder as your own content | `rpengine.distribute` | ## Editing in a browser No account needed. See [Editing in a browser](/rp-engine/editing). | Command | What it does | Permission | | --- | --- | --- | | `/rp edit ` | Open it in the right editor in your browser | `rpengine.edit` | | `/rp edit` | The links you have open, and how long they have left | `rpengine.edit` | | `/rp edit close` | End them | `rpengine.edit` | ## Permissions Each subcommand has its own node, `rpengine.`, and `rpengine.admin` grants all of them. Everything defaults to op except `rpengine.emote`, `rpengine.emotes`, `rpengine.chat.icons` and the six dialog click nodes (`var`, `page`, `slot`, `click`, `run`, `quick`), which every player has. [Permissions](/rp-engine/permissions) has the full list. --- Source: https://resourcepack.ai/docs/rp-engine/config # Configuration The settings live in `plugins/RPEngine/config.yml`, which the plugin writes the first time it starts. Every setting has a working default. Many settings apply on `/rp reload`; restart the server to be sure a change has taken effect. When an update adds a setting your file should show you, RP Engine writes it into your `config.yml` on the next start, explanation and all, without touching anything else in the file. The old file is kept beside it as `config.yml.v.bak`, and the console says what changed. ## Serving the pack ```yaml host: mode: upload port: 8181 public-address: "http://127.0.0.1:8181" ``` A player's game downloads a pack over HTTP, from a link the server sends it. `host.mode` decides where that link points: | Mode | How it works | Use it when | |---|---|---| | `upload` (default) | Each pack is uploaded to ResourcePack AI's pack host (`packs.resourcepack.ai`), free, and players download it from there. A pack is only uploaded again when it changes. | Almost always. Nothing to open or configure, and it works behind a proxy and on any host. | | `same-port` | Your server serves the packs itself, on its Minecraft port. | You want nothing to leave your machine, and players connect to this server directly. | | `own-port` | Your server serves the packs itself, on a second port. | You want nothing to leave your machine and you run a proxy (Velocity, BungeeCord). You have to open the port and set the address. | | `none` | Packs are built into `output/` but not served. | You host the zips yourself (a CDN, a web server). | With `upload`, your packs are stored on our servers for as long as your server uses them: one nothing has touched for 30 days is deleted, and only the Minecraft client can download them. A pack can be at most 95 MB. `same-port` does not work behind a proxy, because a proxy only passes Minecraft through. The link it sends each player uses the address that player joined with, so there is nothing to configure. `own-port` uses the two other keys: | Key | Default | What it does | |---|---|---| | `host.port` | `8181` | The port it listens on. `0` picks a free one, which is only useful for testing | | `host.public-address` | `http://127.0.0.1:8181` | The address a player's game downloads the pack from. Set it to your server's public IP or hostname and the port above, and open that port (on a hosting panel, allocate it to your server). The plugin cannot work this out itself behind a proxy or NAT | With `upload` you can also keep a copy served from your own server, for any player whose game cannot reach the pack host (a school or work network that blocks it, say). Set `host.fallback-on-download-failure: true` along with `host.port` and `host.public-address` as for `own-port`, and open that port. A player whose download fails is sent your server's link instead, and so is everybody while an upload is failing. It is read at startup. An older config with `public-address` set and no `host.mode` stays on `own-port`, and `host.enabled: false` means `none`. When a player's game cannot download a pack, the console says which link it was sent and what to check, once per restart. `/rp bundles` shows the link each bundle is served at. ### If the upload fails The console says `Could not upload main to the pack host (reason), so this server is serving it on its game port instead`. The reason in brackets says what went wrong. Usually it is one of: - **Your host blocks outgoing connections.** The server has to reach `https://packs.resourcepack.ai`. Ask your host to allow it, or serve the pack yourself (below). - **The pack is over 95 MB.** Make it smaller, or serve it yourself. RP Engine tries the upload again on `/rp reload`, on a restart and every six hours. Until then, players are sent the pack from your game port, which works when they connect to this server directly. **Behind Velocity or BungeeCord** the game port cannot serve a pack, because a proxy only passes Minecraft through, so players get nothing until an upload works. To be safe, set `host.fallback-on-download-failure: true` with a `host.port` and `host.public-address` players can reach (open the port, or allocate it on your hosting panel), or switch to `host.mode: own-port` and skip the pack host entirely. On a Velocity network, [RPE Proxy](/rp-engine/proxy) can send the pack from the proxy instead. ### If players don't get the pack Work down this list: 1. **Read the console after a player joins.** When a player's game can't download a pack, RP Engine names the link it sent and what to change, once per restart. The startup log also warns about a `host.public-address` that can't work. 2. **Try the link yourself.** `/rp bundles` shows the link each pack is served at. Open it in a browser on another network (a phone on mobile data will do). If it doesn't download there, players can't download it either. `/rp push` sends you the pack again. 3. **With `own-port`, check the address.** `host.public-address` has to be a whole `http://` address with your server's public IP or domain and the port: `http://203.0.113.5:8181`, not `203.0.113.5:8181` and never `127.0.0.1`. The port has to match `host.port`, be different from your Minecraft port, and be open to the internet (on a hosting panel, allocated to this server). If you can't open a port, go back to `upload`. 4. **Restart after changing `host:`.** These settings are read when the server starts, so `/rp reload` doesn't pick them up. 5. **Behind Velocity or BungeeCord,** `same-port` can't work. Use `upload`, `own-port`, or [RPE Proxy](/rp-engine/proxy). 6. **Check the player's own setting.** In the multiplayer server list, select the server, press **Edit**, and set **Server Resource Packs** to **Enabled** or **Prompt**. On **Disabled** the game turns down every pack the server sends without asking, and a player who once pressed **No** at the prompt can be left on Disabled. Being sent the pack on every join is normal, not a fault: the server sends it each time, and the game reuses the copy it already downloaded unless the pack has changed. ## The pack and the join prompt ```yaml pack: description: "RP Engine" # format: 46 default-bundle: "main" prompt: message: "" force: false ``` | Key | Default | What it does | |---|---|---| | `pack.description` | `RP Engine` | Shown in the client's resource pack list, with the bundle name added | | `pack.format` | not set | Leave it unset; the plugin picks the right number for your version. Set it only when the startup log says your Minecraft is newer than this RP Engine, then update the plugin and remove it. See [Minecraft versions](/rp-engine/versions#the-pack-format) | | `pack.packsquash.enabled` | `false` | Runs each pack through [PackSquash](https://packsquash.aylas.org/) before players are sent it, for a smaller download. See [Squashing the pack](#squashing-the-pack) | | `default-bundle` | `main` | The [bundle](/rp-engine/bundles) every joining player is sent. Empty sends nothing, for a server that sends packs itself | | `prompt.message` | empty | Text shown when the client asks the player to accept the pack. Empty uses the game's own wording. MiniMessage (``, `<#fa4943>`, ``, ``, ``) and `&` codes (`&c`, `&l`, `&#fa4943`) both work | | `prompt.force` | `false` | `true` disconnects a player who declines the pack | ## Merging other packs Other plugins (Model Engine, BetterHud and the like) build resource packs of their own. List them under `pack.merge` and RP Engine builds them into its pack, so players download one pack instead of one per plugin: ```yaml pack: merge: - "ModelEngine/resource pack" - "BetterHud/build.zip" ``` Each entry is a folder or a `.zip`, relative to the `plugins` folder. They are read again on every `/rp reload`, so after the other plugin rebuilds its pack, reload RP Engine. The other plugin's files are never moved or changed. Turn off the other plugin's own pack sending, or players are sent its pack twice: once inside RP Engine's and once on its own. Where a merged pack and your `content/` folder ship the same file, yours wins. A resource pack zip you drop straight into `content/` is merged the same way; `pack.merge` is for packs that live, and keep changing, somewhere else. ## Squashing the pack [PackSquash](https://packsquash.aylas.org/) shrinks a resource pack, so players download it faster. RP Engine runs it on every pack it builds, if you turn it on: Download PackSquash Get the build for your server's system from its releases page and put it in `plugins/RPEngine/packsquash/` (`packsquash`, or `packsquash.exe` on Windows). Turn it on Set `pack.packsquash.enabled: true` and run `/rp reload`. ```yaml pack: packsquash: enabled: false executable: "packsquash/packsquash" options: "packsquash/packsquash.toml" ``` PackSquash's options are in `packsquash.toml`, written the first time it runs. The defaults keep font and 3D armour textures exactly as they are, because RP Engine's HUDs, dialogs, text effects and 3D armour read exact colours from them. Sounds are re-encoded, which is where most of the saving is; the file says how to stop that. A pack is only squashed again when it changes, so a restart is as quick as before. A pack that comes out no smaller, or that PackSquash would have left files out of, is sent unsquashed and the console says why. On `/rp reload`, a squash that takes longer than 20 seconds finishes in the background and is used from the next reload. ## Sending the pack ```yaml send: before-join: false on-join: true on-reload: true delay: 0 ``` | Key | Default | What it does | |---|---|---| | `send.before-join` | `false` | Sends the packs while the player is still connecting, so they arrive in the world with them already loaded. Needs Paper 1.21.7 or newer; anywhere else the packs are sent on join instead. A big pack keeps the player on the loading screen until it has loaded. Read at startup | | `send.on-join` | `true` | Sends the packs when a player joins. With `before-join` on, only what did not arrive before it. `false` sends nothing at join, for a server that sends the packs itself | | `send.on-reload` | `true` | Sends everybody online the new packs after `/rp reload`. `false` keeps what they have until they next join | | `send.delay` | `0` | How long after joining the packs are sent, in ticks (20 a second). Does not apply to `before-join` | ## How it talks ```yaml chat: icons: false text-effects: true prefix: "RPEngine" colour: prefix: "#3670f8" brackets: "#555555" body: "#aaaaaa" accent: "#3670f8" error: "#ff5555" success: "#55ff55" ``` Every line the plugin writes starts with `[prefix]`, and the colours are yours to change so it matches your server. `accent` colours names, counts and codes, and the headings in `/rp` help. Colours are hex, with or without the `#`; anything else falls back to the default. ## Icons in chat `chat.icons: true` lets anybody with `rpengine.chat.icons` (every player, by default) type `:wave:` in chat to draw the [icon](/rp-engine/icons) called `wave`. Use `:mypack:wave:` where two packs use the same name. It is off by default. Text that is not an icon name is left exactly as typed, so `10:30`, `:)` and links are safe. ## Text Effects in chat `chat.text-effects: true` (the default) lets players type `hello` in chat to write "hello" in the [Text Effect](/rp-engine/text-effects) called `fire`. It needs `rpengine.chat.effects.all` for every effect, or `rpengine.chat.effects.` for one, and both default to op. A tag somebody may not use stays as typed. `false` turns it off for everybody. ## Emotes ```yaml emotes: player-commands: true bake-on-join: true rigs: true rig-days: 30 rig-players: 64 cast-permission: "rpengine.emote.cast" nametag-see-through: false held-item-pitch: 90.0 held-item-yaw: 0.0 held-item-roll: 0.0 ``` An emote plays on a rig: a copy of the player's skin, cut into parts, which is part of the pack. | Key | Default | What it does | |---|---|---| | `player-commands` | `true` | Registers `/emote`. Turn it off if another plugin already has `/emote`; `/rp emote` still works, and `/emotereply` is always registered | | `rigs` | `true` | Builds a rig for players who have joined, plus a shared default, so emotes and vehicle seats work without Studio. Needs Minecraft 1.21.4 or newer | | `rig-days` | `30` | Only players seen in this many days get a rig. Anybody else wears the default until they come back. `0` is no limit | | `rig-players` | `64` | The most players with a rig, newest first. Each is about 20 KB of every player's download. `0` is no limit | | `bake-on-join` | `true` | Rebuilds the rigs when somebody joins who has none yet. See below | | `cast-permission` | `rpengine.emote.cast` | The node needed to pull other players into an emote. Empty for no check | | `nametag-see-through` | `false` | Whether an emoting player's name shows through walls. Off, because a see-through name tends to vanish behind nearby models | | `held-item-pitch`, `-yaw`, `-roll` | `90`, `0`, `0` | Calibration for how a held item is turned in a rig's hand. You should not need these; if a held item looks wrong, please report it | **What `bake-on-join` does.** A player the server has never seen has no rig, so they appear as the default skin until the rigs are rebuilt. With this on, the rebuild starts as soon as they join, and anybody else arriving within a few seconds is covered by one follow-up build. Players who are already online are not sent the new pack straight away (a new pack reloads their screen): they get it the next time they are sent a pack anyway, such as on rejoining or with `/rp push`. Until then they see the newcomer as the default. Turn it off to choose the moment yourself; `/rp reload` always includes every rig that has arrived. ## Vanilla recipes ```yaml items: vanilla-recipes: false ``` Whether custom items count as the vanilla item they are made from in the game's own recipes. Off, a tomato made from paper is not paper: it can't make a book, cook in a furnace, go through a stonecutter or repair a tool on an anvil. Your own [recipes](/rp-engine/recipes) and other plugins' recipes work either way. Set it to `true` to let every item in, or let in just one with [`vanilla-recipes: true`](/rp-engine/recipes#vanilla-recipes) on the item. ## Seats ```yaml models: seat-offset: 0.0 ``` Moves every seat on placed models up or down, in blocks. Positive is higher. If everybody sits slightly too high or low on every chair, set the difference here and `/rp reload`. You should not need it. ## Vehicles ```yaml vehicles: seat-offset: 0.0 seat-forward: 0.0 debug-seats: false push-players: false collide: true speedometer: true mount-hint: true seat-rig: true ``` | Key | Default | What it does | |---|---|---| | `seat-offset` | `0.0` | Moves every [vehicle](/rp-engine/vehicles) seat up (positive) or down, in blocks | | `seat-forward` | `0.0` | Moves every vehicle seat toward the front (positive) or back | | `debug-seats` | `false` | Once a second, reports where each rider actually ended up against where the plugin put them. For tracking down one seat that is out while others are fine | | `push-players` | `false` | Whether a moving vehicle shoves players out of the way. Mobs are always shoved, and vehicles always stop at walls | | `collide` | `true` | Whether vehicles bump into each other. The result depends on speed, angle and each vehicle's weight. Turn it off for a race track or a crowded car park | | `speedometer` | `true` | Shows the driver's speed above the hotbar in km/h, yellow while the tyres slide. A single vehicle can opt out; see [the speedometer](/rp-engine/vehicles#the-speedometer) | | `mount-hint` | `true` | Tells somebody the controls once when they get in. Passengers are told which seat they took either way | | `seat-rig` | `true` | Shows occupants sitting or standing in their emote rig, even when the pack gives the seat no emote. Off shows ordinary players, which costs fewer entities on a full vehicle | Which controls a vehicle uses depends on your server: Paper 1.21.4 and newer reads the movement keys, anything else steers by where the driver looks. See [Minecraft versions](/rp-engine/versions). ## Plants ```yaml blocks: tripwire-frozen: auto ``` How many [plants](/rp-engine/blocks#plants) fit depends on whether Paper has frozen tripwire updates (`block-updates.disable-tripwire-updates` in `config/paper-global.yml`): 32 if it has, 2 if not. `auto` reads Paper's setting. `true` or `false` states it outright, for a server whose Paper config lives somewhere else. Saying `true` when tripwire is not frozen makes neighbouring plants turn into each other. ## HUD overlays ```yaml overlays: refresh-ticks: 30 # 1 to 50 trigger-ticks: 2 # 1 to 20 ``` `refresh-ticks` is how often a HUD a player is wearing is re-sent, in ticks (20 a second). A value a plugin sets through the API is drawn on the next tick whatever this says. This is for the placeholders the server works out itself, like `{health}` and PlaceholderAPI's: lower makes those smoother, at one packet per wearer per redraw. Above 50 the action bar starts to fade between redraws. `trigger-ticks` is how often a HUD's state triggers, such as sneaking or holding an item, are checked. 1 puts a HUD on or takes it off on the very tick the player does the thing, for a minigame that needs it exact; 20 is once a second. A check only sends a packet when the answer changes, so lowering it costs very little. ## VFX ```yaml vfx: max-sprites: 4000 # 0 for no limit ``` How many [VFX](/rp-engine/vfx) sprites may be alive at once across the whole server. Each sprite is a display entity. When a new effect would go over it, the oldest effects playing end to make room, so a cast always plays. 4,000 is a few ms of tick time; see [what it costs](/rp-engine/vfx#what-it-costs) for measurements and what we recommend for busy and quiet servers. ## Mob skills ```yaml skills: debug: false ``` `debug: true` logs every [skill](/rp-engine/skills) line a custom mob runs, and what it aimed at, to the console. It is for finding out why a skill did not fire, and it is noisy, so leave it off otherwise. ## Dialogs ```yaml dialogs: click-sound: "ui.button.click" # blank for none click-volume: 0.25 # 0 to 1 click-pitch: 1.0 # 0.5 to 2 ``` A click on a dialog's picture makes no sound in the game, so the plugin plays this one. Any sound event works, the game's or one your pack adds. A Studio dialog can choose its own [click sound](/dialogs#click-sounds), for the whole dialog or one piece, and that takes priority. A hand-written dialog can too: ```yaml shop: json: shop.json click-sound: { sound: block.note_block.chime, volume: 0.5, pitch: 1.5 } click-sounds: # the clicks that run this command - { command: "rp page mypack:shop.ranks", sound: entity.experience_orb.pickup } ``` `click-sound: ""` silences a dialog's clicks. ## Studio ```yaml sync: url: "wss://sync.resourcepack.ai/connect" server-token: "" edit: enabled: true url: "https://studio.resourcepack.ai" distribution: api-url: "https://studio.resourcepack.ai" mode: content ``` Nothing connects to Studio unless somebody runs `/rp sync`, `/rp edit` or `/rp distribute`. Leave the URLs alone. | Key | Default | What it does | |---|---|---| | `sync.server-token` | empty | Only for a server the Studio account owner runs themselves. With a token, Studio can see who is online and push to them without a pairing code | | `edit.enabled` | `true` | `false` turns off [`/rp edit`](/rp-engine/editing) | | `distribution.mode` | `content` | Where a pack bound with [`/rp distribute`](/distribution) goes. `content` keeps it in `content/studio-/` and builds it into RP Engine's own pack. `cdn` sends it to each player on its own, the build for their version, and writes nothing to `content/`. Needs a restart | ## Other plugins' shaders ```yaml shaders: merge: true notify-players: true ``` Some plugins draw their HUD by replacing one of the game's core shaders, and the text shader is the usual one: BetterHud does, and so do Studio's HUD shader objects and the player heads in Studio dialogs. A player's game keeps only one copy of each core shader, from whichever pack is highest in their list, so without help only one of the two draws. With `merge: true`, RP Engine reads the other plugin's pack from its folder, combines its own text shader with theirs so both draw, and puts the result inside its own pack. Players get no extra pack and no extra loading screen. RP Engine's pack has to sit above the other plugin's, so when it has merged a shader, a joining player's packs wait up to three seconds for the other plugin's to arrive first. If it comes later than that, RP Engine sends its own again, on top. Some plugins (BetterHud among them) send theirs in a way that removes every other pack the player has, so without this RP Engine's would be gone. The console says what happened, and so does chat for players with `rpengine.shaders.notify` (ops), when it happens and when they join. Set `notify-players: false` to keep it to the console: - **Merged**: which plugin's shader, and on which Minecraft versions. - **Could not merge**: which versions, and why. A plugin whose own shader cannot compile on a version gets this, because merging would only replace a working shader with a broken one. BetterHud 2.0.0 is one: its shader does not compile on 1.21.6 to 1.21.11, so update BetterHud. - **Shader clash**: another core shader both packs replace. Only the text shader is merged, so for anything else, only one of the two draws. RP Engine can merge its text shader with one other plugin's. If two other plugins both replace it, it says so and merges neither. `merge: false` turns merging off and leaves only the warnings. ## Usage count ```yaml telemetry: enabled: true ``` Every 30 seconds the plugin tells resourcepack.ai it is running, so we know how many servers and players use RP Engine and its addons. It sends three things: a random id it created the first time it started (kept in `plugins/RPEngine/server-id`; delete the file and a new one is made), the number of players online, and the names of installed plugins that depend on RP Engine. No address, server name, version, player names or UUIDs, worlds or content. A failed send is silently dropped. `enabled: false` sends nothing at all, from the next restart. ## Update check ```yaml update-check: true ``` Tells the console at startup, and players with `rpengine.update` (ops) when they join, that a newer RP Engine is out. --- Source: https://resourcepack.ai/docs/rp-engine/content # The content folder Everything you add to RP Engine lives in `plugins/RPEngine/content/`. Each folder in there is one pack. The plugin reads them all, builds one resource pack out of them, and sends it to your players. ## What can go in content/ Each entry in `content/` has to be one of these: | What you put there | How it is recognised | |---|---| | **A content pack**: your own items, models, sounds and so on, in YAML | A folder with a `pack.yml` in it. The rest of this page is about these | | **A resource pack**, such as one exported from Studio | A `.zip`, or a folder with `pack.mcmeta` and `assets/` at the top. See [Adding a resource pack](/rp-engine/resource-packs) | | **Another plugin's pack** | An [ItemsAdder](/rp-engine/itemsadder), [Nexo or Oraxen](/rp-engine/nexo-oraxen), [CraftEngine](/rp-engine/craftengine), [Model Engine](/rp-engine/modelengine) or [BetterModel](/rp-engine/bettermodel) folder, copied in as it is | A folder that is none of these is skipped with a warning (see [below](#if-the-console-warns-you)). A folder's name is its **namespace**, the first half of every ID in it (`mypack:ruby`). Use lowercase letters, digits, `_`, `.` and `-` only. See [IDs and namespaces](/rp-engine/ids). ## A content pack's layout ``` plugins/RPEngine/content/ mypack/ pack.yml required items/ *.yml blocks/ *.yml sounds/ *.yml music/ *.yml fonts/ *.yml icons screens/ *.yml huds/ *.yml dialogs/ *.yml recipes/ *.yml entities/ *.yml custom mobs skills/ *.yml mob skills drop-tables/ *.yml spawners/ *.yml liquids/ *.yml vehicles/ *.yml emotes/ *.json or *.yml armor3d/ *.yml 3D armour sets objects/ *.yml 3D shader objects and their sequences text-effects/ *.yml vfx/ *.yml or *.json assets/ → assets/mypack/ in the built pack textures/ models/ Blockbench files sounds/ overrides/ → assets/minecraft/, for replacing vanilla art resourcepack/ optional: a resource pack, copied as it is pack.png optional ``` You only need the folders you use. A pack with one item has `pack.yml`, `items/` and `assets/`. ## The rules **The folder decides the kind.** A file in `items/` defines items, a file in `sounds/` defines sounds. Top-level keys in a file are IDs, so you do not nest them under an `items:` key. One file can declare many things, the file name does not matter, and subfolders are only for your own organisation: `items/weapons/swords.yml` adds nothing to the ID. **Only the folders above are read.** There is no `models/` folder: a placed model is a [`place:` block on an item](/rp-engine/models). Any other folder is warned about by name, which catches typos like `item/` and `Sounds/`. **A mistake skips one definition, not the pack.** See [Reloading](/rp-engine/reloading). ## pack.yml As short as a name: ```yaml name: My Pack ``` Or with everything it accepts: ```yaml name: My Pack description: Swords and statues author: You version: 1.0.0 bundles: [main] # which built packs this content goes into enabled: true # false skips the whole pack without deleting it ``` Leave `bundles:` out and the pack goes into `main`, which every player gets. See [Bundles](/rp-engine/bundles). ## assets/ and overrides/ **`assets/`** becomes `assets/mypack/` in the built pack. It is namespaced, so nothing in it can collide with another pack or with vanilla. An item `mypack:ruby` looks for its texture at `assets/textures/item/ruby.png`. Name the files in it in lowercase. Minecraft refuses a capital letter anywhere in a resource pack path, so a texture called `Ruby.png` would never load. RP Engine lowercases such a file in the built pack, and everything that names it, and warns you, but renaming the file is what quiets the warning. **`overrides/`** becomes `assets/minecraft/`. It is how you replace vanilla art: a different dirt texture, a new font, a changed sound. overrides/ is the one place two packs can fight Two packs both replacing `assets/minecraft/textures/block/dirt.png` is a real conflict. The namespace that comes later alphabetically wins, and both are named in a build warning. `assets/models/` holds Blockbench `.bbmodel` project files or exported Java `.json` models. The `.bbmodel` is the better choice, because its textures are inside it. See [Items](/rp-engine/items#3d-items). ## YAML or TOML A definition file can be `.yml`, `.yaml` or `.toml`, mixed freely in one folder. They mean exactly the same thing. ```toml [ruby] material = "DIAMOND" name = "&cRuby" [chair.place] facing = "cardinal" seat = 0.5 ``` Quote an ID with a / or a . in it Both mean something to TOML, so `weapons/sword` has to be written `["weapons/sword"]`. The error message says so when it happens. ## If the console warns you `/rp reload` (and every startup) lists every problem at once, each with the file and the ID. The common ones: | Warning | What it means | Fix | |---|---|---| | `No pack.yml, so this is not a content pack` | The folder is not one of the [shapes above](#what-can-go-in-content). Usually a resource pack unzipped one folder too deep, so `pack.mcmeta` is not at the top | Add a `pack.yml` if it is your content. If it is a resource pack, move its contents up so `pack.mcmeta` and `assets/` sit directly inside the folder, or drop the original `.zip` in instead | | `is a plain resource pack ... did nothing` | You put a `.yml` file inside a resource pack folder (one with `pack.mcmeta` and `assets/`, such as a Studio export). RP Engine copies that folder into the pack as art and never reads definitions from it | Make a separate content pack: a new folder in `content/` with a `pack.yml`, your `.yml` in its `items/` folder and the PNG in its `assets/textures/item/` | | `files have capital letters in their names` | A file in `assets/` is named with capitals, like `Aal.png`. Minecraft would skip it, so RP Engine lowercased it in the built pack | Nothing is broken. Rename the files to lowercase (and the `texture:` that names them) to quiet the warning | | `Folder name is not a valid namespace` | The folder has capitals, spaces or other characters | Rename it: `My Pack` to `my_pack` | | `Not a content category, so nothing in it was read` | A folder in your pack that RP Engine does not read, often a typo (`item/`, `Sounds/`) | Rename it to one from [the layout](#a-content-packs-layout), or move art into `assets/` | | `No texture at assets/mypack/textures/item/ruby.png` | The item has no picture where its ID says. It works, but shows as a purple-and-black square | Put the PNG at `content/mypack/assets/textures/item/ruby.png` (the namespace is the folder, not a folder inside `assets/`), or name another file with `texture:` | | `No model at assets/models/chair.bbmodel or assets/models/chair.json` | The item says `model: chair` and no such file exists. It falls back to its flat sprite | Save the Blockbench project as `content/mypack/assets/models/chair.bbmodel`, or fix the name in `model:` | | `info.namespace says X but the folder is Y, and the folder wins` | An ItemsAdder pack's config names a different namespace from its folder. Its IDs are `Y:something` | Fine as it is, unless other configs refer to `X:something`. Then rename the folder to `X` | | `... already exists, so this zip was not unpacked` | A zip of that name was unpacked before, and that folder is kept in case you edited it | Delete the folder, then reload, to replace it with the zip | ## Moving to another server Copy the whole `plugins/RPEngine/` folder with the plugin jar. If you want to copy only what matters: | Copy | Why | |---|---| | `content/` | Your packs | | `config.yml` | Your settings | | `blocks.json` | Which vanilla block each custom block is stored as. **Without it, every custom block in the world turns into a different block** | | `model-numbers.json` | Below Minecraft 1.21.4, the numbers on custom items in inventories and the world. Lose it and items change into other items | | `liquids.json`, `spawners.yml` | Your pools and the spawners made in game | Leave out `output/` and `cache/` (rebuilt on start) and `unpacked-zips/`. Leave out `server-id` too if the old server keeps running, so the two are counted separately. Placed models are stored in the world itself, so they move with the world files. --- Source: https://resourcepack.ai/docs/rp-engine/craftengine # Moving from CraftEngine RP Engine reads CraftEngine pack folders as they are, so you can move your items, furniture, blocks, images, emoji, sounds and recipes across without rewriting them. 1. Copy a pack folder out of `plugins/CraftEngine/resources/` into `plugins/RPEngine/content/`. 2. Rename the folder to the `namespace:` its `pack.yml` declares (see the warning below). 3. If the pack uses CraftEngine's templates, copy `default_templates/` in too. 4. Start the server, or run `/rp reload`, and read the console for warnings. ``` plugins/RPEngine/content/ default/ ← a CraftEngine pack folder, renamed to its namespace pack.yml configuration/ ← items, blocks, furniture, images, recipes... resourcepack/ ← its art, in any namespace, minecraft: included default_templates/ ← CraftEngine's templates, if the pack uses them ``` There is nothing to turn on. A folder with a `pack.yml` and a `configuration/` folder is read as CraftEngine's, and a single CraftEngine file also works inside a pack of yours, which is handy for moving over a piece at a time. It is built against CraftEngine 26.9. The folder is the namespace The **namespace** is the first half of every ID (`default:topaz`). In RP Engine it is the folder's name, not the `namespace:` in `pack.yml`. CraftEngine's own `default_assets` declares `namespace: default`, so as it stands it loads as `default_assets:topaz`. Rename the folder to `default` and the ids match. The load warns once per namespace that differs. ## Templates and version keys CraftEngine packs lean on **templates**, and RP Engine applies them: `template:` (one or a list) with `arguments`, `overrides` and `merges`, `${arg}` and `${arg:-default}` placeholders, and the typed arguments (conditions, lists, maps, self-increasing numbers, arithmetic expressions). Templates are shared across every loaded pack, as in CraftEngine. Most packs use CraftEngine's bundled `default:` templates, so copy its `default_templates` folder in beside them; a template that cannot be found is a warning naming it. **Version keys** such as `$$>=1.21.2:`, `$$<=1.21.1:`, `$$1.20.5~1.21.4:` and `$$fallback:` are resolved for the server's version, and `a::b:` deep keys are nested, so a pack written for several versions loads the part meant for yours. A pack's `subpacks:` are chosen the same way. ## What comes across | CraftEngine | RP Engine | |---|---| | item | an [item](/rp-engine/items) | | `material`, `lore`, `unbreakable`, `enchantments` | the same | | `item_name`, `custom_name` | `name`, with MiniMessage colours turned into colour codes and `` keys resolved to their English text | | `attribute_modifiers` | [`attributes`](/rp-engine/stats) | | `food`, `max_damage`, `max_stack_size`, `enchantment_glint_override` | `food`, `durability`, `stack`, `glow` | | `model:` as a path, a `minecraft:model` definition or an inline model | `model`, read from the pack's `resourcepack/` where it already is | | `model:` with `select`, `condition` or `range_dispatch` | its default model | | `texture:` / `textures:` | the item's art; tools get a handheld model, several textures become layers | | `equippable` and `equipments:` | [`armor`](/rp-engine/armour), drawn from the equipment texture it names | | `block_item` with a block of the same id | a [custom block](/rp-engine/blocks) carrying the item's name | | block `state` with `auto_state: solid` or a mushroom group | the block, on note blocks or mushroom stems | | block `textures` (1 to 6) or `model` | its model; textures become a cube, column, top-bottom or six-sided model | | block `hardness`, `correct_tools`, place sound | `hardness`, `tool`, `sound` | | block `luminance` | `light` | | block `loot` | `drop`: the item the table drops when mined normally | | block `states`: `properties`, `appearances` and `variants` | [`properties`](/rp-engine/blocks#turning-and-states) and `appearances`, state for state, each appearance's turn (`x`, `y`, `uvlock`) kept | | an appearance with several models | `random:`, a look picked as each is placed | | a block whose appearances are a stair's, slab's, door's or trapdoor's `state:` (`stairs_block`, `slab_block`, `door_block`, `trapdoor_block`) | that [`shape:`](/rp-engine/blocks#stairs-slabs-doors-and-other-shapes), on **the same vanilla block** the pack took, so the ones already in a world stay. A grate or bulb hidden in a vanilla grate or bulb does the same | | `auto_state` `tripwire`, `sugar_cane`, `sapling` and the like, or a plant behaviour | a [plant](/rp-engine/blocks#plants), on cut tripwire | | `leaves_block`, or a leaves `auto_state` | `shape: grate`, the see-through full block | | `crop_block`, `stem_block`, `sapling_block` (`grow_speed`, `light_requirement`, bone meal) | [`grow:`](/rp-engine/blocks#growing) on `age` or `stage` | | `falling_block` · `strippable_block` (`stripped`) · `simple_storage_block` · `lamp_block` | `falls` · `strip` · `storage` · `shape: bulb` | | a right-click `cycle_block_property`, or `toggleable_lamp_block` | `click:`, so a lamp or a safe switches its look | | furniture, inline under `furniture_item` or on its own | [`place:`](/rp-engine/models) | | ground, wall and ceiling variants | `surface` | | `rotation: any`, `four`, `eight` | `facing`: free, 4 ways, 8 ways | | interaction hitbox | `width` and `height` | | shulker hitbox | `solid: true` | | seat | `seat` | | `glowing_furniture` light | `light` | | furniture loot | `drop` | | item, block and furniture `events` | [actions](/rp-engine/actions), with `particle` as a [`particle`](/rp-engine/actions#steps) step: see below | | image | an [icon](/rp-engine/icons), with its height and ascent | | image grid (`grid_size`, or `chars` as rows) | one icon per cell, `__` from 0, the way `` counts | | emoji with a `:word:` keyword | an icon called `word`, so `:word:` works in chat with [chat icons](/rp-engine/config#icons-in-chat) on | | shaped, shapeless, smelting, blasting, smoking, campfire and stonecutting recipes | [recipes](/rp-engine/recipes), with vanilla and pack ingredients | | `smithing_transform` and `smithing_trim` recipes | `smithing` and `smithing_trim` recipes; `merge_components: false` turns off `copy-data` | | `brewing` recipes | `brewing` recipes, which need Paper | | `shaped_transform` and `shapeless_transform` recipes | ordinary shaped and shapeless recipes, with a warning: the result is made fresh rather than inheriting the source ingredient's data | | sound | a [sound](/rp-engine/sounds), with volume, pitch, stream and subtitle | | `resourcepack/` | copied into the pack RP Engine builds, as written | Art stays where CraftEngine keeps it. A pack that references `minecraft:item/custom/ruby` from `resourcepack/assets/minecraft/` resolves with no file moved, and so does a model CraftEngine would generate from textures: it is written inline instead. ## What does not Each of these is a warning naming the ID when the pack loads, so nothing is dropped silently. Most of a world does not come across Block and furniture *definitions* translate. Most of what is already placed in a world does not: CraftEngine stores its furniture its own way, and a block hidden in a note block, a tripwire or a mushroom took a vanilla state CraftEngine chose, where RP Engine hands out a spare state of its own. Those have to be rebuilt, and the load names each block it applies to. **Shapes are the exception.** A stair, slab, door or trapdoor keeps the very vanilla block the pack took, so the ones already standing in a world are still those blocks after the move. **Block behaviours with no equivalent**, each named with its reason: fences and fence gates, buttons and pressure plates (RP Engine has none of those to take over), spreading like grass, drawers and items shown on a block (`storage:` is the nearest), seats on blocks (a [placed model's seat](/rp-engine/placement-options#sitting) is the answer here), bouncing, particles from a standing block, chimes, budding, decaying, stacking, snowy variants, placement rules, dropped experience and biome tints. Also what a sapling or stem becomes when it has finished growing (a tree, a fruit), and `entity_renderer`. The block still loads. **Some of a block's states**: a state's own settings (a different light or hardness per state), since an RP Engine block's states share one set; property values RP Engine blocks cannot have, which are drawn at their default; a block with more states than a note block's pool holds, whose extra states are placed as its first; and leaves' decay properties, which are the game's own rules. A `toggleable_lamp_block` switches its look on a click but gives no light; `shape: bulb` is the block whose light redstone switches. **Item settings and furniture interactions**: fuel, repair items and the like, and furniture interactions. The item still loads. **Events and functions with nothing to land on**: `step` and `fall`, a left click on a block or a piece (that is mining or breaking it here); functions such as titles, teleports and anything that switches a furniture variant or a block state other than by a right-click; a `run` with a delay; anything behind a condition other than a permission; and a function aimed at other players. **More than one of something**: extra furniture elements, hitboxes, seats and lights, and the extra models of an item model definition. The first comes across and the warning names the rest. **Pinned characters**: an image's `char` is ignored, because RP Engine hands out its own. Write the icon as `:::` rather than the character. **Dye recipes**, **smithing recipes without a template or an addition** (RP Engine's smithing table takes all three), and any recipe with a tag or a choice of ingredients. Those are skipped whole and named, rather than loaded with an ingredient missing. **Sounds that replace a vanilla one**: put those in `resourcepack/assets/minecraft/sounds.json`. **Sections with no RP Engine equivalent**: categories, jukebox songs, loot tables for vanilla blocks and mobs, paintings, advancements, world features and the rest. Each is one line in the load, with a count. **Entities**: CraftEngine's `entities:` section is not a mob of its own. Each entry names an existing entity type (a vanilla mob, or one another plugin such as MythicMobs spawns) and gives every one of them attribute values and tags for CraftEngine's damage rules; there is no model, name or spawn in it. An RP Engine [entity](/rp-engine/entities) is a new mob wearing a model, so there is nothing for one to take, and the load says so. To put a model on mobs that already exist, [bind one](/rp-engine/mobs). ## Good to know **Seats are worth a look in game.** CraftEngine measures a seat from the entity it mounts the rider on and RP Engine from where they sit, so seats are converted and the load says so. If a chair sits people slightly wrong, adjust its `seat:`. **English is what comes across.** Names and lore that read a `lang:` key are resolved to their English text once, at load. A pack's other languages are noted in one warning. --- Source: https://resourcepack.ai/docs/rp-engine/dialogs # Dialogs A dialog is a menu the server opens on a player's screen, in Minecraft 1.21.6 and newer: a title, some text, and buttons that run commands. Use one for a welcome screen, a warp menu, a settings page or a staff tool. Unlike a [screen](/rp-engine/screens), it isn't a chest wearing a picture; the game draws real buttons. ![A settings dialog open in game](/images/dialogs.webp) ## Making one Write it in a `dialogs/` folder of your [content folder](/rp-engine/content): ```yaml # mypack/dialogs/menus.yml welcome: title: Welcome body: - Glad you made it. - Pick somewhere to start. columns: 2 # how many buttons sit side by side buttons: - label: Spawn command: spawn # the PLAYER runs it, with their permissions tooltip: Back to the middle - label: Shop console: warp shop {player} # the CONSOLE runs it: no /warp for players - label: The wiki url: https://example.com ``` Run `/rp reload`, then `/rp dialogs` lists them and `/rp dialog mypack:welcome [player]` opens one. RP Engine or Dialog Engine? [Dialog Engine](/dialog-engine) is a separate plugin for dialogs only. The two don't share dialogs: a dialog written here opens with `/rp dialog`, and one written for Dialog Engine opens with `/de open`. Use RP Engine's if you already run RP Engine; use Dialog Engine if dialogs are all you need, or you want its inputs and click events. ## What a button does Each button does one thing, named by its key: | Key | What happens on a click | |---|---| | `command:` | The player runs the command, with their own permissions | | `console:` | The console runs it, with `{player}` filled in for whoever clicked | | `suggest:` | The command is typed into their chat box, not sent | | `url:` | Opens a link (the game asks first) | | `copy:` | Copies the text to their clipboard | | `dialog:` | Opens another dialog by its id | | none | Just closes the dialog, like an Ok button | A button also takes `label:` (default "Ok"), `tooltip:` and `width:` (default 150). One button makes a notice, two a yes/no, three or more a grid. **`console:`** is for a command a player should only get from the dialog, such as a warp they can't type. Typing it in chat does nothing, and nobody can change a word of it. A button pressed twice runs twice, so for something given once, check first or close the dialog after it. **Several commands on one button**: give `command:` or `console:` a list, up to 16. They run in order and stop at the first that fails. ```yaml - label: Starter kit console: - give {player} bread 8 - give {player} torch 16 - label: Go command: [spawn, "kit starter"] # the PLAYER runs both ``` ## Opening it with a command of its own ```yaml shop: command: shop # /shop opens it on whoever types it permission: myserver.shop # optional title: Shop ``` If another plugin already has `/shop`, that plugin keeps it and the console says so. ## Dialogs about somebody Write `{target}`, or any name, anywhere a dialog has words or a command, and give it a value when you open it: ```yaml punish: title: Punish {target} buttons: - label: Mute 1h command: mute {target} 1h ``` ``` /rp dialog mypack:punish target=Steve Admin ``` opens it for Admin, titled "Punish Steve". `{player}` and the other [built-ins](/rp-engine/hud#live-values-in-text) describe whoever the dialog is shown to, and PlaceholderAPI answers the rest when it is installed. ## Settings per player Declare settings under `vars:` with every value they may take, and a button changes one with `/rp var`: ```yaml settings: title: "Sidebar: {show_sidebar?off:Hidden|on:Shown}" vars: show_sidebar: ["on", "off"] buttons: - label: "Turn it {show_sidebar?off:on|on:off}" command: "rp var show_sidebar {show_sidebar?off:on|on:off}" ``` `{name?value:words|...}` picks the words for the player's value, and the last entry when none matches. Settings survive restarts, and other plugins read them as `%rpengine_var_show_sidebar%`. Quote `on`, `off`, `yes` and `no`, or YAML reads them as true and false. ## Pages Make each page a dialog of its own and turn between them with `/rp page`: ```yaml settings: title: Settings after: none # stay up until the next page replaces it buttons: - label: Audio command: rp page mypack:settings_audio - label: Close command: rp page close ``` A player can only reach a page through a button that runs exactly that command. After a server restart, page turns happen instantly on the client. ## What happens after a click `after:` decides: | Value | What the player sees | |---|---| | `seamless` (default) | The dialog stays up until the server has answered, so a dialog the click opens replaces it with no flicker | | `close` | Closes at once | | `none` | Stays open. It is drawn again after a `console:` button or a command list runs, so changed values show | | `wait_for_response` | The game's "waiting for response" screen | `can_close_with_escape: false` stops Esc closing it (a dialog with no buttons always closes with Esc). `pause: true` pauses a single-player world, and only works with `close` or `wait_for_response`. ## Click sounds The game makes no sound for a click on a dialog's picture, so RP Engine plays one. Choose your own per dialog or per command: ```yaml shop: click-sound: { sound: block.note_block.chime, volume: 0.5, pitch: 1.5 } click-sounds: - { command: "buy {item}", sound: "" } # this click is silent ``` ## On the Quick Actions key (G) Minecraft 1.21.6 added a Quick Actions key, G by default. `quick-action:` puts a dialog on it; with several, G shows a list. ```yaml hub: title: "Hub for {player}" quick-action: true # G opens the dialog itself (Paper only) warps: title: Warps quick-action: mode: launcher # G opens a button that opens it fresh label: Warps # its name in G's list ``` The key opens a copy the player received as they joined, so with `true` its placeholders show what was true at join time. `launcher` opens a one-button screen instead, whose button opens the dialog fresh. Spigot, and any dialog with a `permission:` or the player's items in it, always uses the launcher. **A change takes a server restart**, and the console says when one is due. ## Reacting to a click in your own plugin RP Engine has no "button clicked" event: a button runs a command, so register that command in your plugin and handle it there. To change what a dialog shows, set values from code with `dialogs().set(...)` and open it again. See [Dialogs in the API](/rp-engine/api#dialogs). Moving an item in a Studio dialog's slots fires `DialogSlotMoveEvent`, which you can cancel. ## Dialogs from Studio A [dialog made in Studio](/dialogs) arrives when you push the pack to your server (see [Testing on your server](/testing/plugin)), with the id `studio:` (and `studio:.` for its pages), drawn in Studio's art. Everything above is set in Studio's editor instead: live values, settings on switches and sliders, pieces shown only to some players ("Show when"), item slots, live progress bars, player heads and click sounds. RP Engine fills each in for the player it is shown to. A dialog exported from Studio as a JSON file works without a push too: ```yaml shop: json: mypack/dialogs/shop.json # path inside the content folder ``` The same `json:` key takes any `minecraft:dialog` file you wrote yourself, for anything the keys on this page can't say. ## Versions A dialog needs **Minecraft 1.21.6**. On an older server the definitions still load and `/rp dialogs` says why nothing opens. A [screen](/rp-engine/screens) is the older way to make a menu and works on every version. --- Source: https://resourcepack.ai/docs/rp-engine/drops-and-spawners # Drops and spawners This page covers what a [custom mob](/rp-engine/entities) drops when it dies, and spawners, which keep a number of mobs alive in one place. Both also read MythicMobs' format, so a MythicMobs `Drops:` list, a `DropTables/` file or a `Spawners/` file can be copied across as it is. Needs RP Engine 0.2.53 or newer. ## Drops ```yaml rhino: type: POLAR_BEAR model: zoo:rhino drops: - {item: minecraft:leather, min: 1, max: 3} - {item: zoo:horn, chance: 0.25} - minecraft:bone xp: 5 ``` **`drops:` replaces the vanilla loot entirely.** A mob with no `drops:` drops nothing but its experience. Each entry is an item, vanilla (`minecraft:leather`) or one of a pack's (`zoo:horn`): | Key | Default | What it is | |---|---|---| | `item` | required | The item | | `min`, `max` | 1, 1 | How many | | `chance` | 1 | The chance it drops at all, 0 to 1 | `xp` is the experience it leaves, a number or a range (`xp: 5to10`). It defaults to 0. Whatever a mob wears from [`equipment:`](/rp-engine/entities#equipment) drops only on its own `drop-chance`, rolled on top of `drops:`. A plugin can still change the loot in RP Engine's `EntityDeathEvent`; see the [Plugin API](/rp-engine/api#events). ### MythicMobs drop lines MythicMobs' one-line drops work in the same list, so a `Drops:` block copies straight in: ```yaml drops: - minecraft:leather 1to3 0.5 # item, amount (or a range), chance - exp 10to20 # experience - droptable rare_loot # a table from drop-tables/ (also table, dt) - command{c="give diamond 1"} 1 0.1 # a console command ``` | Line | Drops | |---|---| | ` [amount] [chance]` | That item. The amount may be a range: `1to3` | | `exp ` | Experience. The amount may be a range | | `droptable ` | One roll of a [drop table](#drop-tables). `table` and `dt` work too | | `command{c="..."} [amount] [chance]` | Runs a command as the console. The killer is `` | | `nothing` | Nothing: a pick in a weighted table that gives nothing | ## Drop tables A drop table is a loot list a mob names rather than repeats, in MythicMobs' `DropTables` shape. Put them in `drop-tables/` (the `droptables/` folder works too): ```yaml # drop-tables/loot.yml RareLoot: TotalItems: 2 # exactly two picks, each by weight (the third number) Drops: - minecraft:diamond 1 1 - minecraft:emerald 1to3 3 - nothing 1 6 # a pick that gives nothing BossChest: MinItems: 1 # or a count in a range, by weight MaxItems: 3 Conditions: [ "night" ] # must pass on the mob as it dies TriggerConditions: [ "isplayer" ] # must pass on its killer Drops: - minecraft:gold_ingot 2to5 1 - droptable RareLoot 1 1 # tables can name tables, 8 deep ``` | Key | What it does | |---|---| | `Drops` | The lines, as above | | `TotalItems` | Pick exactly this many lines, each by its weight (the third number on the line) | | `MinItems`, `MaxItems` | Pick a number of lines in this range, by weight | | `Conditions` | [Conditions](/rp-engine/skills#conditions) the mob must pass as it dies | | `TriggerConditions` | Conditions its killer must pass | Without `TotalItems`, `MinItems` or `MaxItems`, each line rolls its own chance, as a mob's own `drops:` do, and the third number is a chance rather than a weight. A table whose conditions fail drops nothing from that table. A bare table name is looked for in the mob's own pack first, then in any pack; `otherpack:RareLoot` names another pack's. Tables can name other tables, up to 8 deep. ```yaml golem_king: type: IRON_GOLEM model: bosses:golem drops: - droptable BossChest - exp 50to80 ``` ## Spawners A spawner keeps some of one mob alive round a point while players are near, like MythicMobs' spawners. Write them in `spawners/`, or make them in game. ```yaml # spawners/arena.yml pit: mob: zoo:ghoul location: world,120.5,64,-40.5 # or {world: world, x: 120.5, y: 64, z: -40.5} max-mobs: 3 mobs-per-spawn: 1 cooldown: 10 warmup: 0 radius: 4 activation-range: 32 leash-range: 16 heal-on-leash: true level: 0 ``` | Key | Default | What it does | |---|---|---| | `mob` | required | The custom mob it spawns | | `location` | required | Where: `world,x,y,z`, or a map | | `max-mobs` | 1 | How many may be alive at once, 1 to 64 | | `mobs-per-spawn` | 1 | How many each time | | `cooldown` | 10 | Seconds between spawns (up to 86,400) | | `warmup` | 0 | Seconds a player must be near before the first | | `radius` | 0 | How far round the point they are spread, up to 64 blocks | | `activation-range` | 32 | It spawns only while a player is this near (up to 256). 0 is anywhere in the world | | `leash-range` | 0 | One that strays further than this is pulled back. 0 never pulls | | `heal-on-leash` | `false` | Heal it when it is pulled back | | `level` | 0 | The [level](/rp-engine/entities#levels) they spawn at. 0 rolls the mob's own `level:` | MythicMobs' spellings (`MobName`, `MaxMobs`, `ActivationRange`, `LeashRange`, `HealOnLeash` and the rest) read the same. A spawner only spawns while its chunk is loaded and a player is in range. Its mobs never despawn, and after a restart it recognises the ones it already made, so it never doubles up. A content folder's spawners have ids like everything else (`arena:pit`) and change with `/rp reload`. ### Making one in game Spawners made with a command are kept in `plugins/RPEngine/spawners.yml`: | Command | What it does | |---|---| | `/rp spawner create [x y z [world]]` | Makes one, where you stand if you give no place | | `/rp spawner set ` | Changes a setting: `max-mobs`, `cooldown`, `warmup`, `radius`, `activation-range`, `leash-range` and the rest | | `/rp spawner remove ` | Removes it. Its mobs stay | | `/rp spawner list` | Every spawner | | `/rp spawner info ` | One spawner's settings | Each verb has its own permission (`rpengine.spawner.create` and so on), all granted by `rpengine.spawner`. A content folder's spawner shows in `list` and `info`, but is changed only in its file. See [Permissions](/rp-engine/permissions). --- Source: https://resourcepack.ai/docs/rp-engine/editing # Editing in a browser `/rp edit` opens a model, texture or vehicle from your server's content folder in ResourcePack AI's web editors, and writes your changes back to the file on your server when you are done. Use it to tweak a model or repaint a texture without downloading the file, opening Blockbench and uploading it again. ``` /rp edit mypack:chair ``` You get a link in chat. Click it and that thing opens in the right editor. Move the cubes, paint the texture, press **Send to server**, and `assets/models/chair.bbmodel` on your server changes and the content reloads. No account, no sign-in, nothing to install. The link works once and lasts three hours. ## What it opens You give it only the ID. The plugin works out which editor to use: | What the ID is | Where it opens | | --- | --- | | An item with a `model:` | The model editor: geometry, paint, display, animation | | An item with no `model:` | The pixel editor, on its sprite | | A vehicle | The vehicle editor: seats, handling, effects | Other kinds of content (sounds, screens, recipes) have no editor yet, and the command tells you so. The ID tab-completes, and only things that can be opened are offered. ``` /rp edit the links you have open, and how long they have left /rp edit close end them ``` ## Nothing changes until you press Send to server The editor saves your work as you go, but none of that reaches your server. Your files change once, when you press **Send to server**. If you try something and change your mind, close the tab and nothing has happened. ## What crosses, and what does not Only the thing you named: one model and its textures, one texture, or one vehicle's settings. Not the rest of your pack, and not your config. The link is the key. Anybody who has it can edit that one thing until it expires, so do not paste it anywhere public. `/rp edit close` ends it early. ## Models A model comes back as the same kind of file it went out as. A `.bbmodel` (the Blockbench project, which [Models](/rp-engine/models) recommends) comes back as a `.bbmodel`, with its geometry, bones, animations and art still in one file. Anything Blockbench keeps that the plugin does not read, like display settings and texture names, is left as it was. An exported `.json` comes back as a `.json`, with its PNGs written beside it where they already were. A texture you add in the editor goes into your item's texture folder. A model written inline in the item's YAML, or one named by a resource location (`minecraft:item/...`), is not a file in your pack's `assets/models/`, so it cannot be opened. Your original is never half-replaced The plugin checks the file it is about to write loads as a model before saving anything, and refuses in chat if it would not. Each write goes to a temporary file first and is then moved into place, so a crash or a full disk cannot leave half a model behind. ## Vehicles In the vehicle editor you drag a figure onto a seat, and that is where somebody sits. Only that vehicle's entry in your `vehicles/*.yml` is rewritten. Other vehicles in the file, blank lines and comments between them are left alone. Comments inside the edited vehicle are lost. The vehicle's model is shown so the seats have bodywork to sit in, but it is read-only there. Open the item it wears to change its shape. ## Textures The pixel editor opens square PNGs up to 256×256. An animated strip (a tall image with a `.mcmeta` file beside it) is refused rather than squashed. ## Turning it off ```yaml # config.yml edit: enabled: true ``` Set `enabled: false` and `/rp edit` says it is switched off instead of doing anything. `rpengine.edit` is the permission, and it is a serious one: whoever holds it can rewrite files in your content folder from a browser. It defaults to op. See [Permissions](/rp-engine/permissions). ## This is not the same as Sync [`/rp sync`](/rp-engine/commands#studio) sends a pack from a Studio account to a player on your server, so you can try it before it ships. It needs an account and a pairing code. `/rp edit` goes the other way and needs neither: your content folder is the source, and your changes land back in it. Content from a Studio pack, synced or [distributed](/distribution), has a `studio:` id. Studio is its source, and the pack's folder in `content/` is replaced each time you publish, so `/rp edit studio:` doesn't open an editor here. It links to the pack in Studio instead: change it there and publish again. --- Source: https://resourcepack.ai/docs/rp-engine/emotes # Emotes An emote is an animation played on a player, in their own skin: a wave, a dance, a handshake. While it plays, the player is hidden and a copy of them (a rig) performs it in their place. When it ends they are put back exactly where they were. ![Players doing emotes: a wave, a cheer, a dance and a point](/images/emotes.webp) ``` /emote wave /emote handshake Steve /emote stop ``` Tab completion lists every emote on the server, and for an emote that needs a partner it offers the players who could join in. ## Every player needs a rig An emote has two parts: - **The rig** is a model of the player, cut out of their skin. It is made automatically. - **The animation** is keyframes, made once. It moves bones by name, so the same wave fits every player. Rigs travel inside the resource pack, so the pack needs one for each player who emotes. RP Engine builds them itself from the skin of everyone who joins. A player joining for the first time shows as a default figure until that rebuild finishes (you often notice it when they sit in a seat or a vehicle). The new pack goes to whoever joins next, and to players already online the next time they are sent a pack: nobody's game reloads just because someone walked in. | config.yml | Default | What it does | |---|---|---| | `emotes.rigs` | `true` | Build rigs on this server at all | | `emotes.bake-on-join` | `true` | Rebuild when someone new joins. Off, and `/rp reload` builds whoever has arrived | | `emotes.rig-days`, `emotes.rig-players` | 30, 64 | Only players seen in the last 30 days get a rig, at most 64, newest first. Each rig adds about 20 KB to everybody's download. 0 is no limit | | `emotes.player-commands` | `true` | Registers `/emote`. Off, and it's still there as `/rp emote` | | `emotes.cast-permission` | `rpengine.emote.cast` | Who may pull other players into an emote. Empty for no check | Building rigs needs Minecraft 1.21.4 or newer. On older servers, rigs that arrive in a Studio push still work. ## Getting emotes onto a server Make them in [Studio](https://studio.resourcepack.ai), then send the pack straight to your game (a **push**): Pair In Studio, open your pack and press **Sync** to get a pairing code. In game, run `/rp sync `. See [Testing on your server](/testing/plugin). Push Push from Studio. The pack arrives with the emotes in it, and rigs are built for everyone on that sync. Emote Type `/emote` and press Tab. Or write them by hand: see [Hand-authored emotes](#hand-authored-emotes). `/rp emotes` lists what the server has right now. If somebody joined after the push, push again. ### Sharing a push A sync belongs to one player. To let someone else test the same pack, add them to yours: | Command | What it does | |---|---| | `/rp sync add ` | Invites them; they accept or deny | | `/rp sync who` | Who is on your sync | | `/rp sync remove ` | Takes them off, and the pack comes off them | | `/rp sync leave` | Leaves somebody else's sync | | `/rp sync stop` | Ends your sync for everybody | ### Models inside an emote An emote can carry a pack model as a prop: a chair, a sword, a barbell. If part of the model moves, it plays on the emote's own clock, so a lifted barbell stays in the lifter's hands. ## Emotes with a cast Some emotes take more than one person, like a handshake or a hug. The lead names the others, and everyone is moved into position, turned to face each other, and put back afterwards. Nobody is moved until every participant and spot has been checked, and the emote ends for everyone at once. Invited players are asked first, with accept and deny buttons (they run `/emotereply`, which every player can use, so anyone can refuse). | Permission | What it allows | |---|---| | `rpengine.emote` | Play an emote | | `rpengine.emotes` | List emotes | | `rpengine.emote.cast` | Pull other players into an emote (they are still asked) | | `rpengine.emote.force` | Skip the invitation, for staff running an event | ## Movement sets A movement set is a group of emotes you wear rather than play once: a walk, a run, an idle, used for as long as you have it on. You put one on the same way: ``` /emote strut ``` Groups and single emotes share one list of names, so they can't clash. ### Walk cycles follow the player, not the clock Walk, sprint and crouch-walk cycles play according to how far the player has moved, not how much time has passed. Standing still, the legs stop; on soul sand they slow; with a speed potion they keep up. Feet don't slide. Draw each cycle for Minecraft's normal pace and it plays as drawn: | State | Draw it for | |---|---| | Walk | 4.317 blocks per second | | Sprint | 5.612 blocks per second | | Crouch-walk | 1.295 blocks per second | Idle, crouching in place and jumping play at their drawn speed. Changing pace doesn't restart anything: the engine picks up the new cycle on the same leg and blends between them. ## What stops an emote Being hit, moving (for most emotes), `/emote stop`, or a plugin (`EmoteStartEvent` can be cancelled, and `Emotes.stop` ends one). Any invisibility the player had before comes back afterwards, minus the time the emote took. ## Playing one automatically, such as on join RP Engine has no "on join" trigger for emotes. Use a plugin that runs commands when a player joins, and have it run `/emote ` **as that player** (the command only plays on whoever runs it), or call `engine.emotes()` from your own plugin. Give the rebuild a few seconds for a first-time player, or they emote as the default figure. A [VFX](/rp-engine/vfx#playing-one) can be played the same way with `/rp cast`. ## Hand-authored emotes A pack can carry its own emotes in an `emotes/` folder. One file can hold as many as you like, keyed by name: ```json { "wave": { "name": "Wave", "length": 1.2, "loop": false, "animators": { "rightArm": { "rotation": [ { "time": 0, "value": [0, 0, 0] }, { "time": 0.3, "value": [-160, 0, -20], "interpolation": "smooth" }, { "time": 1.2, "value": [0, 0, 0] } ] } } } } ``` This is exactly what Studio's emote editor exports, so the easy way is to make it there and paste the entry. YAML works as well as JSON. | Part | Values | |---|---| | Bones | `head`, `body`, `rightArm`, `leftArm`, `rightLeg`, `leftLeg`, `rightForearm`, `leftForearm`, `rightShin`, `leftShin`, and `root` (the whole figure, about the hip) | | Channels | `rotation` (degrees), `position` (pixels), `scale` | | Timing | `time` and `length` in seconds; `loop` repeats it | **Emote names are shared across the whole server**, not per pack, because `/emote wave` uses the bare name. Two packs both defining `wave` is an error, so prefix yours (`mypack_wave`) if other people will install your pack. ### Props Carry a model with `props`, beside `animators`: ```json "props": [ { "id": "right", "modelId": "mypack:skate_right", "attach": "rightShin", "offset": [2, -16, 0], "scale": 1 } ] ``` | Field | What it is | |---|---| | `modelId` | One of your items (whatever wears the model you want) | | `attach` | A bone name, `root` for the whole body, or `none` to stay where it was put | | `offset` | Where the model's centre sits, in pixels from the rig's origin, which is a block above the feet | | `animator` | The prop's own motion, with the same channels as a bone | | `animation` | One of the model's own animations, played on the emote's clock | **BetterModel's player animations load as emotes too.** Drop its plugin folder in and every animation in `players/` becomes one. See [Moving from BetterModel](/rp-engine/bettermodel). Hand-authored emotes play on the rigs the engine bakes, which needs Minecraft 1.21.4 or newer. On older servers they load but play on nobody. --- Source: https://resourcepack.ai/docs/rp-engine/entities # Entities A custom entity is a real Minecraft mob that wears one of your models: a temple guard, a rhino, a boss. Its AI and pathing are a vanilla mob's, so it fights, wanders and dies like one, but it looks like your model, plays an animation for whatever it is doing, and has the stats, sounds and name you give it. ```yaml # entities/mobs.yml rhino: type: POLAR_BEAR # required. Chosen for behaviour: the looks are replaced model: zoo:rhino # assets/models/rhino.bbmodel, or an item id name: "&7Rhino" health: 40 damage: 6 speed: 1.2 scale: 1.0 height: 1.4 head-bone: head tags: [zoo] animations: spawn: appear idle: idle walk: walk run: gallop attack: charge hurt: flinch death: fall sounds: ambient: zoo:grunt hurt: zoo:ouch death: entity.cow.death drops: - {item: minecraft:leather, min: 1, max: 3} - {item: zoo:horn, chance: 0.25} xp: 5 ``` To make one: 1. In your [content folder](/rp-engine/content) (here `zoo`), save the Blockbench model as `assets/models/rhino.bbmodel`. 2. Write the mob in `entities/`, as above. `model: zoo:rhino` names that file (`:`). You don't need an item for it. 3. Run `/rp reload`, then `/rp spawn zoo:rhino` spawns one where you stand. `/rp entities` lists them all. `model:` can also name an item that wears the model, and several mobs can wear one model. If it names neither a model nor an item, the mob spawns as the plain vanilla mob and `/rp reload` warns about it. Needs RP Engine 0.2.51 or newer; [skills](/rp-engine/skills), the options under [More options](#more-options), drop tables and spawners need 0.2.53. Skills Timed attacks, phases, summons and auras, written as MythicMobs skill lines. Drops and spawners What it leaves behind, weighted drop tables, and keeping mobs alive round a point. ## Everything a mob takes | Field | Default | What it does | |---|---|---| | `type` | required | The vanilla mob it is underneath. See [Choosing the type](#choosing-the-type) | | `model` | none | The model it wears: a file in `assets/models/`, or an item id | | `name` | none | Its name, with `&` colour codes. See [Its name](#its-name) | | `name-visible` | shown when named | `true` always shows the name, `false` only when somebody looks at the mob | | `health` | the mob's own | Max health, 1 to 1024 | | `damage` | the mob's own | Attack damage | | `speed` | 1 | A multiple of the mob's own speed, 0.1 to 4 | | `knockback-resistance` | the mob's own | 0 to 1 | | `scale` | 1 | How big the model is drawn, 0.1 to 16. The hitbox is unchanged | | `height` | the mob's own | How tall the hitbox is, in blocks (1.20.5 and newer) | | `turn` | 0 | Which way the model faces, in degrees. See [Facing](#facing) | | `head-bone` | none | A bone that turns toward whatever the mob is fighting | | `ai` | `true` | `false` stands it still for ever | | `burns` | `false` | `true` lets daylight set it alight, like a zombie | | `silent` | `false` | Mutes the mob's own sounds | | `tags` | none | Scoreboard tags added when it spawns | | `animations` | none | One of the model's animations per state. See [Animations](#animations) | | `sounds` | the mob's own | Ambient, hurt, death, attack and step. See [Sounds](#sounds) | | `drops`, `xp` | nothing, 0 | What it drops. See [Drops](/rp-engine/drops-and-spawners) | | `hurt-flash` | `true` | Flashes red when damaged | | `follow-range` | the mob's own | How far it spots something to chase, 1 to 128 blocks | | `fire-immune` | `false` | Fire, lava, magma blocks and burning do no harm, and it never catches fire | | `glowing` | `false` | Draws the model with the glowing outline | | `boss-bar` | none | A boss bar with its name and health. See [Boss bars](#boss-bars) | | `ranged` | none | It shoots. See [A mob that shoots](#a-mob-that-shoots) | | `spawning` | none | It appears on its own. See [Spawning on its own](#spawning-on-its-own) | | `skills` | none | What it does besides walk and bite. See [Skills](/rp-engine/skills) | The fields that came over from MythicMobs (armour, equipment, levels, factions, templates and the rest) are under [More options](#more-options). ## Choosing the type Pick `type` for how it should behave, not how it should look. A zombie hunts players, a polar bear wanders and fights back, an iron golem guards, a pig wanders and runs when hit, an allay drifts, a phantom swoops, an armour stand does nothing at all. It must be a mob that can be spawned. It is genuinely that mob: every other plugin sees it as one, and `tags` are how the rest of your server finds yours: `@e[tag=zoo]` in a command block, a condition in another plugin, or a `/kill` that clears one kind and not another. A custom mob is never bred, tamed, ridden, sheared, milked or traded with, never spawns as a baby or with a jockey, and never turns into something else (a drowned zombie, a struck pig). A name tag and a lead still work on it, unless `prevent:` says otherwise. ## How the model is worn The mob's own body is made invisible, not removed, so players hit it where the model appears to be. The model stands on the ground the mob stands on: its bottom (pixel 0 in Blockbench) is at the mob's feet, whatever the type and size. `scale:` sizes only the model. `height:` sizes the hitbox, and its width grows with it; that needs 1.20.5 or newer, and older servers keep the mob's own box. A custom mob you spawn never despawns, unless you say so with [`despawn:`](#more-options). One that [spawned on its own](#spawning-on-its-own) despawns like the mob it replaced. Whenever a mob wearing a model goes without dying (despawned, removed on peaceful, removed by another plugin), its model goes within a tick or two. ### Facing At `turn: 0` the side Blockbench calls **North (-Z)** is the front, as in Model Engine, so a model made for Model Engine walks forwards unchanged. | The model was built facing | `turn` | |---|---| | North (-Z) | `0` | | East (+X) | `90` | | South (+Z) | `180` | | West (-X) | `270` | Mobs made in Studio are turned for you. `/rp bind` and MythicMobs' `rpmodel` have no `turn:`, so a model you put on somebody else's mob should be drawn facing North. ### The head `head-bone:` names a bone that turns toward whatever the mob is targeting, as an [`h_` bone](/rp-engine/bones) does. The bone has to move in at least one animation: a bone that never moves is drawn as part of the still body and has nothing of its own to turn. A model's other bones work too: `b_` bones are hitboxes of their own, `p_` bones are seats, and `tag_name` is where the name floats. See [Bones that do something](/rp-engine/bones). ### Hurt flash When it takes damage the model goes red for about a third of a second, as a vanilla mob does (a red outline instead for a still model, or on servers older than 1.21.4). `hurt-flash: false` turns it off. ## Animations `animations:` maps each state to one of the model's animations, by name. The states, most important first: | State | When | Plays | |---|---|---| | `death` | It dies. The model stays for the animation (at most five seconds), then goes | once | | `spawn` | It was just spawned | once | | `attack` | It hits something, or fires at it | once | | `hurt` | It takes damage | once | | `run` | It moves fast, or chases what it is fighting | loop | | `walk` | It moves | loop | | `idle` | It stands | loop | When several apply, the one higher in the list plays. A *once* animation plays to its end and the mob goes back to what it was doing; only a more important one cuts it short, so a mob hit mid-bite keeps biting, and a mob killed mid-bite falls over. A blank loop falls through: with no `run` it walks, with no `walk` it idles, with no `idle` it stands in its rest pose. A blank once-animation simply doesn't play, and neither does a state naming an animation the model doesn't have. Animations can also be played from a [skill](/rp-engine/skills) (`animate`), and a skill can change which animation a state plays from then on (`defaultstate`), for a boss that limps once it is badly hurt. ## Sounds ```yaml sounds: ambient: zoo:grunt # every 8 to 20 seconds while somebody is near hurt: zoo:ouch death: entity.cow.death # a vanilla sound event works too attack: zoo:snort step: zoo:thud ``` Each is a [sound](/rp-engine/sounds) from a pack (`zoo:grunt`) or a vanilla sound event. Setting any of them silences the mob's own sounds, so a rhino built on a polar bear does not growl like one. ## Its name The name floats just above the model, not over the hidden body: at the model's top, or at its `tag_name` bone if it has one, whatever the type and `scale:`. `name-visible: true` shows it always. `false` shows it only to a player whose crosshair is on the mob, within reach and not through a block, as vanilla does for a named mob. Unlike a vanilla name it is not drawn through walls, so it never vanishes inside the model. `&` colours and `` [Text Effects](/rp-engine/text-effects) work in it. A name can carry live values, kept current until a name tag renames the mob: | In `name:` | Shows | |---|---| | `{hp}` | Its health now | | `{max_hp}` | Its max health | | `{hp%}` | Its health as a percentage | | `{stance}` | Its [stance](/rp-engine/skills#stances-and-phases) | | `{level}` | Its [level](#levels) | ```yaml name: "&6Golem King &7{hp}/{max_hp}" ``` A name tag, `/data` or a plugin renaming the mob changes it within half a second, and the name goes the moment the mob dies. ## Boss bars ```yaml golem: type: RAVAGER model: mypack:golem name: "&2Moss Golem" boss-bar: {color: GREEN, style: SEGMENTED_10, range: 40} ``` A boss bar with the mob's name (its name tag's, else its id) and health, shown to every player within `range` blocks. | Key | Default | What it is | |---|---|---| | `color` | `PURPLE` | PINK, BLUE, RED, GREEN, YELLOW, PURPLE or WHITE | | `style` | `SOLID` | SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12 or SEGMENTED_20 | | `range` | 32 | Blocks, 1 to 256 | | `fog` | `false` | Thickens the fog for the players who see it | | `darken-sky` | `false` | Darkens their sky | | `music` | `false` | Plays the boss music | `boss-bar: true` is all the defaults. A skill can also put up bars of its own with `barcreate`, for a boss with a shield bar beside its health. ## A mob that shoots ```yaml archer: type: SKELETON model: mypack:mushroom ranged: projectile: snowball # arrow, snowball, small_fireball, fireball, wither_skull, trident damage: 3 # per hit; 0 keeps the projectile's own range: 18 # blocks, 2 to 64 cooldown: 2 # seconds between shots, 0.25 to 60, when RP Engine shoots ``` `ranged: snowball` is shorthand for the projectile alone, with the rest at their defaults (arrow, the projectile's own damage, 16 blocks, 2 seconds). A skeleton, stray or bogged (on 1.21.4 and newer) shoots with its own AI: it keeps its distance, strafes and aims like a skeleton, at the skeleton's own pace, so `cooldown` is not used. Any other `type` shoots every `cooldown` seconds while its target is in range and in sight. Either way its `attack` animation and sound play as each shot leaves, not when it lands. A fireball or a wither skull explodes without breaking blocks, and nobody can pick up a custom mob's arrows. ## Spawning on its own ```yaml desert_ghoul: type: HUSK model: mypack:ghoul spawning: worlds: [world] biomes: [desert, "*badlands*"] replaces: [HUSK, ZOMBIE] chance: 0.1 time: night min-light: 0 max-light: 7 min-group: 1 max-group: 2 max-per-chunk: 2 ``` | Key | Default | What it does | |---|---|---| | `worlds` | every world | The worlds it spawns in | | `biomes` | every biome | Biome names (`minecraft:` optional), with `*` matching anything: `*forest*` | | `replaces` | its own kind | The vanilla mobs it stands in for | | `chance` | 0.1 | The share of matching natural spawns it takes, 0 to 1 | | `time` | `any` | `day`, `night` or `any` | | `min-light`, `max-light` | 0, 15 | The light level where it appears | | `min-group`, `max-group` | 1, `min-group` | How many appear together, up to 16 | | `max-per-chunk` | 2 | No more extra group members once a chunk holds this many, up to 64 | It **takes the place of** natural spawns rather than adding to them: when a matching vanilla mob spawns, yours replaces it (with up to `max-group - 1` more beside it). So the server's mob caps, difficulty and spawn rules still apply, and peaceful spawns nothing. Without `replaces:` it can stand in for any natural spawn of its own kind: a hostile type for monsters, an animal for animals, a water creature for water creatures. An iron golem, an allay or a villager needs `replaces:`, because nothing spawns naturally as one. Biome tags (`#is_forest`) are not read, and warn at load. Night is game time 12300 to 23850. A mob that spawned on its own despawns when nobody is near, as the mob it replaced would have. ## More options These are MythicMobs' mob options, under RP Engine's names. If you are bringing mobs across from MythicMobs, [Porting your MythicMobs mobs](/rp-engine/mythicmobs#porting-your-mythicmobs-mobs) has the whole mapping. ```yaml knight: extends: brute # everything brute says, then this type: ZOMBIE armor: 12 # armour points, 0 to 30 armor-toughness: 4 # 0 to 20 equipment: # worn for real: armour counts, a weapon hits harder head: minecraft:iron_helmet hand: {item: zoo:axe, drop-chance: 0.1} damage-modifiers: {FIRE: 0, PROJECTILE: 0.5, MELEE: 1.5} invincible: false # true: takes nothing but the void and /kill collidable: true # false: players and mobs walk through it gravity: true despawn: never # never, natural or chunk faction: undead # never targets another mob of its faction level: 1to5 # rolled per mob; or a number per-level: {health: 10, damage: 1, armor: 0.5, speed: 0.02, power: 0.25} prevent: [leash, rename] # name tags and leads stop working on it kill-messages: ["{player} met the knight"] mount: zoo:warhorse # rides this, spawned under it ``` | Field | Default | What it does | |---|---|---| | `extends` | none | Builds this mob on another. See [Templates](#templates) | | `armor` | the mob's own | Armour points, 0 to 30 | | `armor-toughness` | the mob's own | 0 to 20 | | `equipment` | none | What it wears and holds. See [Equipment](#equipment) | | `damage-modifiers` | none | Multiplies each kind of damage it takes. 0 makes it immune | | `invincible` | `false` | Takes no damage but the void and `/kill` | | `collidable` | `true` | `false` lets players and mobs walk through it | | `gravity` | `true` | `false` and it floats where it is | | `despawn` | `never` | `never`, `natural` (when no player is near) or `chunk` (gone when its chunk unloads, never saved) | | `faction` | none | It never targets another custom mob of the same faction | | `level`, `per-level` | 1 | See [Levels](#levels) | | `prevent` | none | `leash` and `rename` stop leads and name tags working on it | | `kill-messages` | none | The death message of a player it kills, one at random. `{player}` and `{mob}` are filled in | | `mount` | none | A custom mob id or a vanilla type, spawned under it for it to ride | | `threat-table` | `false` | It fights whoever has hurt it most. See [Threat tables](/rp-engine/skills#threat-tables) | | `stance` | none | The [stance](/rp-engine/skills#stances-and-phases) it starts in | | `variables` | none | The [variables](/rp-engine/skills#variables) it starts with: `{phase: 1}` | `despawn: natural` is the default for a mob that [spawned on its own](#spawning-on-its-own); `never` is the default for everything else (a command, an egg, a spawner or a plugin). ### Templates `extends:` builds a mob on another one, as MythicMobs' `Template:` does (`template:` reads the same): - a key the mob writes itself wins; - a map (`sounds:`, `animations:`, `boss-bar:`) is merged key by key; - a list is replaced, **except `skills:`**, which is the template's lines followed by the mob's own. A template marked `abstract: true` needs no `type:` and is never a mob itself, so a shared base doesn't show up in `/rp entities`. Templates can extend templates; a loop is a load warning. ```yaml undead_base: abstract: true burns: true faction: undead sounds: {hurt: zoo:rattle} skills: - potion{type=WITHER;duration=60} @trigger ~onAttack 0.2 skeleton_knight: extends: undead_base type: SKELETON model: zoo:skeleton_knight health: 60 ``` ### Equipment `equipment:` takes `head`, `chest`, `legs`, `feet`, `hand` and `offhand`, each a pack's item or a vanilla one, with an optional `drop-chance` (default 0, rolled on top of `drops:`). MythicMobs' list form (`- iron_helmet HEAD`) and its slot numbers work too. **A mob wearing a model shows none of it**, since the model is what is seen. On 1.21.4 and newer each piece is worn but drawn as nothing, so its armour and damage still count. Older servers cannot hide a worn item, so there a modelled mob wears nothing (`armor:` still works). A mob with no model wears its equipment as any mob does. ### Damage modifiers `damage-modifiers:` multiplies each kind of damage the mob takes, by Bukkit's cause names (`FIRE`, `FIRE_TICK`, `LAVA`, `PROJECTILE`, `ENTITY_ATTACK`, `FALL`, `BLOCK_EXPLOSION` and the rest) or MythicMobs' groups `MELEE`, `EXPLOSION` and `BURNING`. 0 makes it immune to that cause: the hit is cancelled, so it doesn't even flinch. The list form `- FIRE 0` works too. ### Levels `level:` is rolled for each mob as it spawns, a number or a range (`1to5`), unless `/rp spawn`, a [spawner](/rp-engine/drops-and-spawners#spawners) or a skill's `summon{level=3}` says which. Each level above the first adds `per-level:`'s amounts: | `per-level` key | Adds to | |---|---| | `health` | Max health | | `damage` | Attack damage | | `armor` | Armour points | | `speed` | The `speed:` multiplier | | `power` | The multiplier its [skills'](/rp-engine/skills) amounts take: `power: 0.25` makes a level 3 mob's skills hit 1.5 times as hard | The level shows in its name as `{level}`, in a skill as ``, and the `level{l=3to5}` condition tests it. ## Spawning one | Command | What it does | |---|---| | `/rp spawn ` | Spawns one where you stand | | `/rp spawn [world] [count] [level]` | Spawns up to 64 at a place, at a level. The world may also come first. This is how the console spawns one | | `/rp egg [player] [amount]` | A spawn egg that hatches that mob where it is used | | `/rp spawner create ` | A spawner that keeps some alive round where you stand. See [Spawners](/rp-engine/drops-and-spawners#spawners) | | `/rp entities` | Every custom mob | An egg used on a vanilla spawner hatches the mob there and leaves the spawner alone. Mobs made in [Studio](/mobs) arrive when you push or publish the pack, and are spawned as `studio:`, exactly like the ones in your content folder. From your own plugin, `engine.mobs().spawn(...)`; see the [Plugin API](/rp-engine/api#custom-mobs). ## On Bedrock Bedrock players joining through Geyser see a custom mob as its model too, sized by `scale:`, turned by `turn:`, playing the same animations and flashing red when hit. A dying mob tips over the way a Bedrock mob does rather than playing `death`, and its name sits over the hitbox. See [Bedrock and Geyser](/rp-engine/bedrock#custom-mobs-and-bound-models). Somebody else's mob To put a model on a mob another plugin spawned, like a MythicMobs boss or a Citizens NPC, see [Putting a model on a mob](/rp-engine/mobs). That page dresses an existing mob; this one creates a new one. --- Source: https://resourcepack.ai/docs/rp-engine/furniture # Working furniture A [placed model](/rp-engine/models) (furniture or decoration put down from an item) can do more than stand there. It can be a cabinet you fill, a gramophone that plays discs, an oven that cooks, a lamp a click switches on, a sofa that joins the pieces beside it, or a sapling that grows. Each is one key in the item's `place:` block, and a piece can have several: ![Furniture models: a stool, a sofa, a desk setup and a drum kit](/images/furniture.webp) ```yaml cabinet: material: PAPER model: cabinet place: storage: true # a container. Right-click to open it jukebox: true # plays music discs states: [...] # looks a click cycles through: a lamp, a door, a TV connects: true # joins its neighbours, like a sofa grow: { ... } # turns into another piece over time ``` Whatever a piece holds (a container's contents, a disc, its current state, how long it has been growing) is saved on the piece itself, in the world. It survives a restart, moves with a copied region and goes back with a rolled-back one. ## Storage A cabinet, a wardrobe, a bin, a crate: ```yaml cabinet: material: PAPER model: cabinet name: "&6Oak Cabinet" place: storage: type: chest # chest | personal | enderchest | disposal | shulker rows: 3 # 1-6 title: "Cabinet" # & colour codes. Default: the item's name, else "Storage" open-sound: minecraft:block.chest.open close-sound: minecraft:block.chest.close ``` `storage: true` is a three-row chest, and `storage: personal` is that type with everything else left at its default. Right-click to open it. | Type | Whose contents | When it is broken | |---|---|---| | `chest` | The piece's. Everybody who opens it sees the same inventory, live | Spills on the ground | | `personal` | Each player's own, shared by every piece of that kind: every wardrobe opens the same wardrobe for the same person, and nobody else sees in | Nothing to spill | | `enderchest` | The player's own vanilla ender chest | Nothing | | `disposal` | Nobody's. **What goes in is deleted when it closes** | Nothing | | `shulker` | The piece's, like a chest | Gives back the item **with the contents inside it**. Place it again and they are back | - Two players in one chest share one live inventory and see each other's moves, so items cannot be duplicated between them. - Breaking a piece closes anyone's open screen first, then spills the contents. A break another plugin cancels spills nothing. A creative-mode break gives no piece back but still spills the contents, as a chest does. - A `shulker` piece always gives back itself, so it ignores `drop:`. Empty, it is the same item as a new one and stacks with them. - `personal` is keyed by the item's ID. Rename `mypack:wardrobe` and everybody's wardrobe starts empty; change the ID back and the old contents return. - You can change `rows:` after people have filled things. A cabinet made smaller still opens big enough for what is in it, and shrinks once the extra rows are empty. [Custom blocks](/rp-engine/blocks#what-else-a-block-does) take the same `storage:` block. ## A jukebox A gramophone, a radio, a boombox: ```yaml gramophone: material: PAPER model: gramophone place: jukebox: volume: 1.0 # 1 is a vanilla jukebox, heard ~64 blocks away. Up to 16 pitch: 1.0 # 0.5-2 permission: mypack.jukebox.use # leave out and anybody may playing-model: mypack:gramophone_on # what it looks like while a disc is in it ``` `jukebox: true` is one with every default. A piece can't be a jukebox and a container at once: the container takes the click, and the load warns you. Right-click it holding a music disc to put the disc in (it leaves your hand unless you are in creative) and the record plays at the piece. Right-click again and the disc pops out and the music stops for everyone. Breaking the piece also gives the disc back. Every vanilla disc works. From Minecraft 1.21, so does a disc a datapack adds, but the server is not told which sound that disc plays, so it plays nothing unless your server has a [sound](/rp-engine/sounds) with the song's own ID. The console tells you once per song. `playing-model` is an item ID (or a model ID with no item of its own) whose model the piece wears while a disc is in it. It does nothing on an [animated](/rp-engine/animation) piece. Late arrivals hear nothing The record is sent once, when the disc goes in, as with a vanilla jukebox. Somebody who walks up halfway through hears nothing until the next disc, and a restart does not resume it. The disc stays in the piece either way. ## A furnace An oven, a stove, a forge. It works like the real thing and looks like your model: ```yaml oven: material: PAPER model: oven place: solid: true furnace: type: furnace # furnace, smoker or blast_furnace title: "Oven" # leave out for the item's name lit-model: mypack:oven_on # what it looks like while it burns speed: 2 # 2 cooks twice as fast as the recipe says recipes: [mypack:pizza] # only these recipes. Leave out for all of its kind's screen: mypack:oven_ui # art for its screen, drawn as a furnace screen effects: # what it does while it burns. false turns it all off particles: { type: flame, count: 2, every: 4, offset: [0, 0.4, 0.45] } sound: false # or a sound id. Leave out for the normal crackle glow: true # the model is drawn fully lit light: 13 # real light, 0-15. Not on a solid piece animation: burning # an animated piece's animation while it burns ``` Left alone, a burning furnace gives off a little smoke and crackles. A solid piece can't give off light, because its block is already a barrier: use `glow` for those. `furnace: true` is a plain furnace, and `furnace: smoker` is a smoker with everything else left alone. Right-click opens the game's own furnace screen, and it uses fuel, cooks your server's recipes and gives experience as a furnace does. | Type | Cooks | Speed | |---|---|---| | `furnace` | Everything a furnace smelts | Normal | | `smoker` | Food | Twice as fast, and fuel lasts half as long | | `blast_furnace` | Ores, armor and tools | Twice as fast, and fuel lasts half as long | It keeps cooking while its chunk is loaded and carries on after a restart. Breaking it drops what is inside and its experience. A smoker or blast furnace shows the furnace screen. Hoppers work as on the real block: from above fills the input, from the side fills the fuel, and a hopper directly underneath takes the result. ## A work block A crafting table, an anvil or a loom that looks like your model: ```yaml workbench: material: PAPER model: workbench place: solid: true station: crafting_table ``` `station:` can be `crafting_table`, `enchanting_table`, `anvil`, `stonecutter`, `smithing_table`, `grindstone`, `loom`, `cartography_table` or `brewing_stand`. Right-click opens the game's own screen for that block, and everything in it works as usual. An enchanting table counts the bookshelves around the piece, and an anvil never wears out. A `brewing_stand` keeps its bottles and fuel on the piece: it brews while its chunk is loaded, carries on after a restart, drops what is inside when broken, and hoppers work on it. It needs Paper 1.20.5 or newer, or Minecraft 26.1 or newer. All the others except the crafting table and enchanting table need Paper, or Spigot 1.21 or newer. ## On a custom block A [custom block](/rp-engine/blocks) can be a furnace, a brewing stand or a work block too, with the same keys. `lit-into` names another block to become while it burns, which is where its burning look and light go: ```yaml stone_oven: model: stone_oven furnace: { speed: 2, lit-into: mypack:stone_oven_lit } stone_oven_lit: model: stone_oven_lit light: 13 ``` In Studio, a model's **Edit details** has a **Works as** setting that does this for a placed model without any YAML. ## States: lamps, doors and screens A click can change a piece. Each entry under `states:` is one more look that a right-click moves to, after the piece as you defined it. One entry is a switch; three are a television with three channels. After the last state, the next click goes back to the start. ```yaml lamp: material: PAPER model: lamp place: light: 0 # dark as placed states: - model: mypack:lamp_on # an item whose model to wear. Leave out to keep it light: 15 # light in this state. Leave out for the piece's own sound: minecraft:block.lever.click # played on arriving in this state door: material: PAPER model: door place: solid: true base-sound: minecraft:block.wooden_door.close # played on going back to the start reset-after: 5s # shuts itself 5 seconds after the last click states: - turn: 90 # degrees added to the way it faces offset: [-0.4, 0, 0.4] # blocks it moves: right, up, forward solid: false sound: minecraft:block.wooden_door.open ``` Anything a state leaves out stays as the piece was defined: a state that only says `light: 15` keeps its model, its collision and its angle. | Key | In a state | |---|---| | `model` | An item whose model it wears, or a model ID with no item of its own | | `light` | 0-15. `0` is dark | | `solid` | Whether a barrier stands in it, like the piece's own `solid:` | | `turn` | Degrees added to the way it faces. A hinged door | | `offset` | `[right, up, forward]` in blocks, the same directions as a [seat's](/rp-engine/placement-options#sitting) `x`, `y` and `z`. A sliding door | | `sound` | Played on arriving in this state | Beside `states:`: - `reset-after:` takes the piece back to the start that long after the last click. Write `10t` for ticks, `10s` for seconds or `2m` for minutes; a bare number is ticks. - `base-sound:` plays when it goes back to the start, by click or by timer. A state's `model:` can name a model you never made an item for, such as `mypack:lamp_on` with only `assets/models/lamp_on.bbmodel` in the pack. The same goes for `playing-model` and the `connects` shapes below. If there is no item or model by that name, the build says so. A piece turns about its own centre and then moves, so a door hinged at one edge is a quarter `turn` plus an `offset` that puts that edge back where it was. It swings over a quarter of a second. Its hitbox, and what a vehicle drives into, stay where it was placed. The state is saved, so a lamp left on is still on after a restart. A piece left open when its chunk unloaded starts its `reset-after` countdown again when the chunk loads. Light and collision follow the piece's rules A solid state gives no light. And the piece only ever changes a block it put there itself: if a player has put a block in the space a model stands in, the model leaves it alone and goes without being solid or lit in that state. On an [animated](/rp-engine/animation) piece, `light`, `solid` and `sound` work, but `model`, `turn` and `offset` do not, and the load says so. Give it a right-click animation as well and a click does both: the state changes and the animation plays. ## Joining up: sofas and counters Pieces of the same kind put side by side can join into one run, the way a sofa or a kitchen counter does: ```yaml sofa: material: PAPER model: sofa place: connects: true # or name any of them: { straight: ..., left: ..., right: ..., inner: ..., outer: ... } ``` | Look | Where the piece is | |---|---| | `straight` | The middle of a row, with one of its kind either side | | `left` | The end with one only on its right | | `right` | The other end, with one only on its left | | `inner` | A corner its back touches | | `outer` | A corner its front touches | Each is an item (or a model) to wear. `connects: true` names them after the piece: `sofa_straight`, `sofa_left` and so on. A piece standing alone wears its own model. A joining piece always faces one of four ways (its `facing:` is treated as `cardinal`) and joins only pieces of its own kind. Corners follow the game's own rule for stairs, and a corner model is turned the way the game turns corner stairs, so a corner drawn like vanilla's inner and outer stairs comes out right. Placing or removing a piece updates the row around it. ## Which click does what A piece can be several of these at once, so a right-click goes to the first that wants it: 1. The piece's own [`interact`](/rp-engine/actions#the-thing-in-the-world) actions run first, and a `cancel` in them stops the rest. 2. **Sneaking** on a piece that has a seat sits, and nothing below runs. 3. A **container** opens. 4. A **furnace** opens. 5. A **work block** opens. 6. A **jukebox** takes a click that puts a disc in or takes one out. 7. **States** move to the next one, and a right-click animation plays with them. 8. A right-click animation plays. 9. Otherwise, a seat is sat on. ## Growing A piece can turn into another piece over time: a sapling into a tree, a crop through its stages. ```yaml rose: material: PAPER model: rose place: grow: into: mypack:rose_stage2 # the item whose placed piece replaces this one after: 10s # the least time it stands first. t, s, m; bare = ticks chance: 0.5 # the chance per check once that has passed. Default 1 light: 9 # the least light at its block. Leave out for any rose_stage2: material: PAPER model: rose2 place: grow: into: mypack:rose_stage3 after: 2m rose_stage3: material: PAPER model: rose3 place: {} # the last stage stays ``` Each piece is checked about once a second. Once it has stood for `after`, each check has `chance` of growing it, so a field does not all change at once. The new piece goes in the same block, facing the same way, and starts its own clock. `into` has to be an item with a `place:` block. If it is not, the load says so and the piece never grows. Growing is not breaking and placing: no break or place event fires, no `remove` or `place` actions run, and the piece itself is not given back. Anything it was holding (a disc, a container's contents) drops on the ground. A piece is only checked while its chunk is loaded. The time keeps counting while nobody is there, so a piece left long enough grows one stage at the first check after somebody comes back. The clock is the game's tick count, so `/time set` or a frozen daylight cycle does not stop growth. [Custom blocks](/rp-engine/blocks#growing) grow differently, through stages of one block. Use those for crops you want to farm in rows. ## From your own plugin `ModelInfo` says what a piece's `place:` block declared: `storage()`, `jukebox()`, `states()` and `grow()`. The engine handles every click itself; cancelling `ModelInteractEvent` stops all of it. Growing fires neither `ModelBreakEvent` nor `ModelPlaceEvent`. See [the plugin API](/rp-engine/api). --- Source: https://resourcepack.ai/docs/rp-engine/gokarts # Go Karts An **addon** for [RP Engine](/rp-engine): a plugin that installs into the engine and adds one thing, rather than a pack you author yourself. Drop it in beside the engine and it brings its own content with it. This one is go-kart racing. Up to eight karts line up on a grid, three red lights go green, and you race three laps: drift through corners for a boost, fly off ramps, take shortcuts, and drive through item boxes for bananas, nitro and rockets. One command builds a whole circuit, and computer drivers can fill the grid when you are short of players. ## Installing It needs **Spigot or Paper, Java 21**, and **RP Engine 0.2.45 or newer**. On an older engine Go Karts says so in the console and turns itself off. A few things need newer versions: | Needs | For | |---|---| | **Paper 1.21.4+** | Steering with A and D. On Spigot you steer by looking | | **RP Engine 0.2.47+** | Karts, helmets and items drawn as icons in inventories (older engines show the shrunk 3D model) | | **RP Engine 0.2.51+** | Bots, and front wheels and steering wheel that turn as you steer | | **Minecraft 1.21.9+** | A visible driver in each bot's kart | Drop it in Put `RPE-gokarts.jar` in `plugins/` beside `RPEngine.jar` and start the server. Go Karts copies its karts, sounds, effects, HUD and results screen into `plugins/RPEngine/content/gokarts/` (RP Engine's content folder, which the engine builds its resource pack from) and reloads the engine once. Build a track As an op, run `/kart track generate main`. It makes a new world for the track, builds the Sunny Meadows circuit there in a few seconds and takes you to it. Nothing in your existing worlds is touched. Race `/kart join`, then `/kart start`. Alone is fine. Add `--withBots` to race computer drivers. If you run Multiverse-Core, Go Karts loads after it, and it loads its own track worlds again every time the server starts. ## Driving | Key | What it does | |---|---| | **W / S** | Throttle; brake, then reverse | | **A / D** | Steer | | **Space** | Handbrake. Held through a corner at speed it is a **drift**: blue sparks, then orange, then purple. Let go for a boost, bigger the longer you held it. In the air, a **trick**, and landing it is a boost | | **F** or click | Use your item | | **Q** | Throw away your item. With empty hands, go back to the last checkpoint if you are stuck or off the road | **The start.** Three red lights a second apart, then green. Hold W too early (when the second light comes on) and you stall. Press it as the lights go green and you get a rocket start. **The track.** Magenta pads on the straights are boost pads, and the lime pad at the lip of a ramp is a jump. Grass and dirt slow you to walking pace, so cutting a corner costs you. Laps count checkpoint by checkpoint, so skipping part of the lap gets you nowhere. Every track has a shortcut (a tunnel, a canyon floor, a frozen lake where the kart slides, a back alley), and either way round counts. Falling off, landing in water, or missing checkpoints for about twelve seconds puts you back on the track. When the winner finishes, everybody else has thirty seconds, then the results screen shows every driver's place, time and best lap, and the track's lap record. ### Items Drive through an item box to spin for an item. What you get depends on your place: the leaders get things to defend with, the back of the field things to catch up. | Item | What it does | |---|---| | Nitro / Triple nitro | One boost, or three | | Overdrive | Every press is a boost for six seconds | | Banana / Banana bunch | Dropped behind you; whoever drives over it spins out. The bunch is three | | Decoy box | Dropped behind you. Looks like an item box (but does not spin) and spins out whoever hits it | | Bumper orb | Rolls ahead of you, bouncing off walls, and spins out whoever it meets, you included | | Rocket | Flies at the kart one place ahead and throws it in the air | | Storm drone | Flies to the leader and strikes everybody within four blocks of them | | Hyper shield | Six seconds where nothing hits you, grass does not slow you, and anybody you touch spins out | | Smoke bomb | Blinds everybody ahead of you for three seconds | | Shockwave horn | Pushes back every kart within seven blocks and clears nearby bananas, decoys, orbs, rockets and a storm drone coming for you | | Static surge | Everybody else loses their item and slows down for three seconds | ### What you see The whole screen is one HUD: your item top left with a live minimap, lap, clock and best lap top right, the standings down the right, and your speed and place bottom right. The start lights and banners (final lap, wrong way, finish) appear in the middle. ## Joining a race | Command | What it does | |---|---| | `/kart join [track]` | Into the track's lobby, a glass box over the infield, until the race starts | | `/kart colour ` | The kart you would like: red, blue, green, yellow, orange, purple, pink or cyan. Everybody in a race gets a different one | | `/kart leave` | Out of the race, with your inventory and position back. Always works, with no permission needed | | `/kart results` | The last race's results | `/kart` also answers to `/gokart`, `/karts` and `/gk`. During a race, players can only run `/kart`, `/msg`, `/tell`, `/w`, `/r`, `/reply`, `/me` and `/list` (change this with `allowed-commands`, or grant `gokarts.bypass.commands`). ## Running races Races start when somebody with `gokarts.start` runs `/kart start [track]`. It joins you first if you are not in. To have a lobby start by itself, set `race.auto-start: true`: once `min-players` are waiting it counts down `lobby-countdown` seconds and starts. `/kart stop [track]` ends a race, or empties a lobby. ### Bots `/kart start --withBots` fills the empty grid slots with computer drivers, and `--withBots=3` adds three. They drive the same karts with the same controls: they follow the road, drift for boosts, jump, use items and recover from crashes. They appear on the minimap, in the standings and in the results, but never in a track's records. Bots need RP Engine 0.2.51 or newer and the `gokarts.start.bots` permission. Their names come from `bots.names` in the config. ### Outside a race `/kart give [colour] [player]` hands over a kart of your own. Right-click the ground to park it, then right-click it to get in. Drifting, boost pads and a speed readout above the hotbar work anywhere. `/kart item [player]` hands a racer an item as if from a box, for testing or events. `/kart as ` runs a subcommand as somebody else, checked against **their** permissions: an NPC that runs `/kart as join` for whoever clicks it is a join button. ## Building a track ### Generate one ``` /kart track generate [prefab] [name] ``` Builds a complete circuit, with walls, kerbs, pads, item boxes, a start gantry, a grandstand and the lobby, **in a new world of its own** (`gokarts_`). It replaces nothing. Generating the same id again makes a fresh world and leaves the old one alone. | Prefab | Track | Lap | Features | |---|---|---|---| | `meadow` (default) | Sunny Meadows | 458 blocks | A jump over a river, a tunnel through a hill | | `desert` | Dune Canyon | 528 blocks | A jump over a canyon, a lower road along its floor | | `frost` | Frostbite Peak | 544 blocks | A figure of eight over a bridge, a frozen-lake shortcut | | `neon` | Neon Nights | 742 blocks, two laps | Midnight city, an elevated road, a tunnel, a back alley | For example, `/kart track generate night neon` builds Neon Nights as the track `night`. To build in an existing world instead: ``` /kart track generate here confirm [prefab] [name] ``` The start line goes under your feet, with the straight running the way you face. It replaces every block in a large box Built `here`, a track replaces everything in a box up to about 200 by 230 blocks, from fifteen below your feet to fourteen above. Without `confirm` it only tells you how big the box is. From the console: `/kart track generate at [prefab] [name]`. **`/kart track undo confirm`** takes back the last generate of that track. A track in its own world deletes the world; one built in place puts back the blocks it replaced (but not the contents of chests or signs). It works after a restart too. ### Set one up by hand On a circuit you built yourself, stand in each place and run: Create it `/kart track create ` The lobby `/kart track setlobby ` where racers wait. The grid `/kart track addgrid ` once per grid slot, facing the way the karts should face. `cleargrid` starts over. Checkpoints `/kart track addcheckpoint [radius]`: the start/finish line first, then round the lap in order, about every fifteen blocks. The radius defaults to 6 blocks. `clearcheckpoints` starts over. Item boxes `/kart track addbox ` at each box. `clearboxes` removes them. Open it `/kart track enable `. If anything is missing it says what. `/kart track laps ` sets this track's laps (0 uses the config's). Use magenta glazed terracotta for boost pads and lime glazed terracotta for jump pads (both can be changed in the config). `/kart track list` shows every track and what it still needs. `disable`, `tp`, `name` and `delete confirm` do what they say (deleting leaves the blocks). ## Permissions One node per command. `gokarts.play` and `gokarts.admin` are shorthand that grant the nodes under them. | Node | What it allows | Default | |---|---|---| | `gokarts.play` | All four racer nodes below | Everyone | | `gokarts.join` | `/kart join` | Everyone | | `gokarts.colour` | `/kart colour` | Everyone | | `gokarts.results` | `/kart results` | Everyone | | `gokarts.ride` | Getting into a kart at all, a parked one included | Everyone | | `gokarts.admin` | Every staff node below | Operators | | `gokarts.start` | `/kart start` | Operators | | `gokarts.start.bots` | `/kart start --withBots` | Operators | | `gokarts.stop` | `/kart stop` | Operators | | `gokarts.reload` | `/kart reload` | Operators | | `gokarts.give` | `/kart give [colour]` | Operators | | `gokarts.give.others` | `/kart give ` | Operators | | `gokarts.item` | `/kart item` | Operators | | `gokarts.as` | `/kart as` | Operators | | `gokarts.track` | Track setup: `list`, `create`, `setlobby`, `addgrid`, `addcheckpoint`, `addbox`, `laps`, `enable`, `disable`, `tp`, `name` and the `clear` commands | Operators | | `gokarts.track.generate` | `/kart track generate` | Operators | | `gokarts.track.undo` | `/kart track undo` | Operators | | `gokarts.track.delete` | `/kart track delete` | Operators | | `gokarts.bypass.commands` | Any command during a race | Operators | ## Configuration `plugins/RPEGoKarts/config.yml`. `/kart reload` rereads it, and `tracks.yml` too unless a race is using it. An update adds new options with their defaults and leaves yours alone. The main settings: | Setting | Default | What it does | |---|---|---| | `race.laps` | `3` | Laps per race | | `race.auto-start` | `false` | Start a lobby on its own once `min-players` (2) are waiting, after `lobby-countdown` (20) seconds | | `race.finish-timeout` | `30` | Seconds the others have once the winner is home | | `race.max-seconds` | `600` | The longest a race can run | | `race.stuck-seconds` | `12` | Seconds without a checkpoint before you are put back | | `karts.cruise-speed` | `13` | Top speed without a boost. Raise it to make karts faster | | `karts.offroad-speed` | `6` | Speed on the `offroad-blocks` (grass, dirt, sand...) | | `karts.boost-pad-block` / `jump-pad-block` | magenta / lime glazed terracotta | Which blocks are pads | | `karts.ice-blocks` | ice, packed ice, blue ice | Blocks the kart slides on | | `boost.*`, `drift.*` | | How strong and long each boost and drift level is | | `items.enabled` | `true` | Item boxes on or off | | `items.odds` | | How likely each item is, one row per place band from the front to the back | | `bots.names` | | Names given to bots | | `allowed-commands` | `msg, tell, w, r, reply, me, list` | Commands racers may use besides `/kart` | | `ui.hud`, `ui.results` | `gokarts:hud`, `gokarts:results` | Point at your own RP Engine HUD or Dialog to replace them. It has to show the same values | A kart's top speed with a boost is the vehicle's `speed:` in `plugins/RPEngine/content/gokarts/vehicles/karts.yml`. **Every word a player reads** is under `messages:` in the same file, in [MiniMessage](https://docs.advntr.dev/minimessage/format.html). --- Source: https://resourcepack.ai/docs/rp-engine/hud # HUD overlays An overlay is a picture drawn on top of the game view while a player plays: a mana bar, a compass, a frame round the edge of the screen. Players need no mod to see one. RP Engine puts the picture in its resource pack and draws it where the game already draws a line of text: - the **action bar**, just above the hotbar, where the name of the item you're holding appears, or - the **boss bar**, at the top of the screen, where a boss's name and health bar appear. ![A custom HUD](/images/hud.webp) There are two kinds: | Kind | What it is | Made with | |---|---|---| | **A picture overlay** | One fixed PNG. To show a change (a mana bar emptying), you swap between several overlays | A few lines of YAML and a PNG, below | | **A Studio shader overlay** | Shapes, labels, player heads and progress bars, with text that updates live | Studio's [Shaders](/shaders) editor. See [Shader overlays from Studio](#shader-overlays-from-studio) | ## Making a picture overlay Add the picture Put the PNG in your [content folder](/rp-engine/content)'s `assets/textures/gui/`, for example `plugins/RPEngine/content/mypack/assets/textures/gui/mana.png`. Describe it Make a `.yml` file in the content folder's `huds/` folder. Each top-level key is one overlay: ```yaml # plugins/RPEngine/content/mypack/huds/overlays.yml mana: file: mana # assets/textures/gui/mana.png. Defaults to the key slot: action_bar # action_bar or boss_bar height: 64 ascent: 32 offset: 0 ``` The overlay's ID is the content folder's name and the key: `mypack:mana`. Reload and show it Run `/rp reload`, then: ``` /rp hud mypack:mana # show it to yourself /rp hud mypack:mana Steve # show it to Steve /rp hud clear Steve # take Steve's overlays away /rp screens # list every overlay and screen ``` An overlay stays on screen until it is cleared. RP Engine keeps re-sending it, because the game fades the action bar out after a couple of seconds. | Field | Default | What it does | |---|---|---| | `file` | the key | The PNG's name in `assets/textures/gui/`, without `.png` | | `slot` | `action_bar` | `action_bar` (above the hotbar) or `boss_bar` (top of the screen) | | `height` | 64 | How tall the picture is drawn, in pixels, 1 to 256. The width follows from the PNG's shape | | `ascent` | 32 | How far the picture is raised above the slot's line of text. Bigger is higher. It can't be more than `height`: a bigger value is lowered to `height`, with a warning | | `offset` | 0 | Moves the picture left, 0 to 512. The slot's line is centred, so the picture moves by half this many pixels: `offset: 40` moves it 20 to the left. At 0 it is centred | **Several overlays at once:** a player can be shown several, but only one is drawn at a time, whichever slot it's in: the one shown most recently. So an `action_bar` overlay shown after a `boss_bar` one replaces it rather than sitting beside it. Hiding the top one brings back the one under it. ## Making it change A picture overlay never changes on its own. A mana bar that empties is several overlays (`mana_100`, `mana_75`, `mana_50` and so on), and something on the server shows the right one at the right time: - a scoreboard or menu plugin that runs `/rp hud` from a [placeholder](/rp-engine/placeholderapi) or a condition, or - your own plugin, through the [API](/rp-engine/api#hud-overlays). For a bar or a number that follows a value smoothly, use a Studio shader overlay instead. ## Shader overlays from Studio Studio's Shaders editor makes far richer overlays: freehand paint, smooth shapes, and labels, player heads and progress bars that update live. See [Shaders](/shaders) for making one. You get it onto the server by pressing **Sync** or by [publishing the pack](/distribution). On the server their IDs start with `studio:`. ``` /rp shaders # list them /rp shader studio:mana_bar # show one to yourself /rp shader studio:mana_bar Steve # show one to Steve /rp shader clear # hide it ``` Rules set in Studio (for example "while holding an item") show one with no command at all, and a plugin can show, hide and feed one through the [API](/rp-engine/api#hud-overlays). A player only sees one if they have the pack it came from. ### Live values in text A shader overlay's labels can hold `{name}` placeholders, filled in for each player just before it's sent. For each name, the first of these that knows it wins: 1. A value your plugin set with `overlays().set(player, name, value)`. A [dialog](/dialogs#live-values) can show the same values. 2. The built-ins below. 3. PlaceholderAPI, if installed: `{vault_eco_balance}` or `%vault_eco_balance%`. A placeholder with arguments is written as it would be anywhere else, such as `%server_time_HH:mm%` or `%stat_{player_name}%`, and is passed to PlaceholderAPI exactly as written. A name nothing knows shows as nothing, rather than as `{name}`. | Placeholder | What it shows | |---|---| | `{player}`, `{name}`, `{displayname}`, `{uuid}` | Who they are | | `{health}`, `{health_max}`, `{health_percent}` | Health, rounded up | | `{food}`, `{air}` | Hunger out of 20, and seconds of breath left | | `{level}`, `{xp}` | Experience level, and progress to the next as a percentage | | `{xp_points}`, `{xp_needed}` | Points into this level, and how many the level takes | | `{ping}` | Latency in milliseconds | | `{world}`, `{x}`, `{y}`, `{z}`, `{direction}` | Where they are, and which way they face | | `{time}`, `{day}` | The world's 24-hour clock, and how many days it has run | | `{gamemode}` | Survival, Creative, and so on | | `{online}`, `{max_online}` | Players online, and the limit | An overlay is re-sent every `overlays.trigger-ticks` ticks (default 2, set in [config.yml](/rp-engine/config)), so a built-in or PlaceholderAPI value is at most that far behind. A value set from a plugin is drawn on the next tick. ### Keeping one in a content folder Instead of syncing, you can keep a Studio HUD in a content folder, using the JSON and the resource pack files Studio's export writes: ```yaml # huds/huds.yml hud: json: mypack/huds/hud.json # path under the content folder ``` Put the exported files in the content folder's `resourcepack/` folder. A boss-bar HUD whose picture uses its own font needs **Paper**; on Spigot, use the action bar. Minecraft draws a dark copy of every line of text one pixel down and to the right, as a drop shadow. Over flat pixel art or lettering made of glyphs that copy can smear. To turn it off for one piece of text, add `"shadow": false` to that entry of the JSON's `runs` list: ```json { "x": 12, "text": "{goal}", "color": "#f00008", "font": "", "shift": "", "shadow": false } ``` Leave it out, or set it to `true`, and the shadow is drawn as usual. Turning it off needs **Paper** on **1.21.4** or newer. On anything else the shadow stays. --- Source: https://resourcepack.ai/docs/rp-engine/icons # Icons An icon is a small picture that behaves like a letter. You can put it in chat, on a sign, in an item's name, on a scoreboard or a boss bar, in a menu title: anywhere the game draws text. ![Custom icons in chat](/images/icons.webp) ```yaml # fonts/icons.yml sword: file: sword # assets/textures/font/sword.png. Defaults to the id height: 10 ascent: 8 ``` The YAML goes in a `fonts/` folder of your [content folder](/rp-engine/content) (here `mypack`), and the PNG in its `assets/textures/font/`. After `/rp reload`, put the icon into any text with `:mypack:sword:`. By the time the text reaches the player it's an ordinary character, so other plugins can show it without knowing about RP Engine. Rank Tags For the badge in front of a player's name, a [rank tag](/rp-engine/rank-tags) is an icon drawn from its words and colours, with no picture to make. ## Height and ascent | Field | Default | What it does | |---|---|---| | `height` | 8 | How tall it's drawn, in pixels (8 is a capital letter). 1 to 256 | | `ascent` | `height`, at most 8 | How far above the text baseline it sits | An ascent equal to the height puts the icon's bottom on the line. Smaller drops it, larger lifts it. The ascent can't be more than the height (the game refuses to draw it), so a bigger value is capped with a warning. To sit an icon in a line of chat, start with `height: 8, ascent: 7` and adjust. ## A sheet of icons Several icons can share one PNG of equal cells, each naming its cell: ```yaml smile: file: emotes # assets/textures/font/emotes.png grid: { rows: 2, columns: 4, cell: 3 } # cells count from 1, left to right, then down height: 8 ascent: 7 ``` `height` and `ascent` are the cell's, not the sheet's. The PNG's width must divide by the columns and its height by the rows. A `file` with a namespace points at that namespace's textures: `minecraft:font/image/emojis` is `assets/minecraft/textures/font/image/emojis.png`. ## Store the ID, never the character Characters move Icons are given characters in ID order, so adding one can shift the ones after it. Anything that writes `:mypack:sword:` and resolves it as it goes is fine. Anything that saved the character itself (in a config file, a database, a sign or a book) shows a different picture after the next reload. `/rp icons` shows the character each icon became, for debugging, not for copying into configs. You don't need your own `assets/minecraft/font/default.json`: RP Engine builds that file from every pack's icons. If a pack does have one (a resource pack dropped into `content/`, or a Studio pack), its characters are kept and RP Engine's icons are given other ones, so both draw. Icons made in Studio come in under the `studio` namespace: a pack synced or published from Studio, or a Studio export dropped into `content/`, lists its icons in `/rp icons`, and each can be typed as `:studio::`. Studio packs exported before RP Engine 0.2.76 don't carry this; export again to get it. ## Using them ``` /rp icons every icon, with its character /rp say :mypack:sword: hi send yourself text with icons filled in ``` Any plugin that runs its text through RP Engine's API can take shortcodes too. See [the plugin API](/rp-engine/api). A shortcode that names no icon is left exactly as written, so typos stay visible. ### Typing them in chat Turn it on in config.yml: ```yaml chat: icons: true ``` Then anybody with `rpengine.chat.icons` can type `:wave:` for the icon called `wave`, or `:mypack:wave:` if two packs use the name. It's off by default. Anything that isn't an icon is left as typed, so `10:30`, `:)` and links are safe. See [Configuration](/rp-engine/config#icons-in-chat). ### More ways to type one, and who may ```yaml heart: file: heart aliases: ["<3", ":love:"] # also typed as these permission: mypack.icon.heart # who may type it, by an alias or by :heart: ``` - **An alias only matches as a word on its own**, with a space or the end of the line on both sides. `<3` becomes a heart in `I <3 you`, but not in `<33`, `a<3` or `<3!`. Aliases can't contain spaces. If two icons claim the same alias, the first by ID keeps it and the console says so. - **`permission`** is needed as well as `rpengine.chat.icons`. Without it, the player's text goes out as typed. Both only apply to typing in chat. Text your plugin sends through the API always takes `:namespace:id:` and ignores them. ## Animated icons An icon can have frames. Draw them as a strip, stacked top to bottom, all the same size: ```yaml loading: file: loading # assets/textures/font/loading.png, 8 frames tall height: 9 ascent: 8 animation: frames: 8 # the PNG's height must divide by this fps: 10 # default 10; 1 to 20 loop: true # default true ``` Or use a GIF, and the build makes the strip for you: ```yaml dance: gif: dance.gif # assets/textures/font/dance.gif height: 11 ascent: 9 ``` A GIF plays at its own speed unless `animation.fps` says otherwise, and `animation.frames` can keep just the first few frames. Players download the generated strip (`dance.gif.png`), not the GIF. | Limit | | |---|---| | 64 frames | Every frame uses a character, out of 6,400 shared by icons, screens and HUDs. A longer GIF keeps its first 64 | | 20 fps | Once per game tick | | 256 pixels a side | Larger GIF frames are scaled down, with a warning | `animation:` works with a strip or a GIF, not a `grid:` sheet. ### Where it moves, and where it does not The server animates an icon by sending the next frame, so an icon only moves in text that keeps being re-sent: - a scoreboard, tab list, hologram or menu showing `%rpengine_icon_mypack:dance%` through [PlaceholderAPI](/rp-engine/placeholderapi), at that plugin's refresh rate; - a plugin's own text, redrawn through [the API](/rp-engine/api). Anything sent once (chat, item names, signs, books, dialogs, `/rp say`) shows the first frame and stays on it. (Animating in the player's own game would mean replacing their text shader, which would clash with other packs that use it.) If frames are different widths, the text after the icon shifts as it plays. To avoid that, give every frame a pixel in the far right column (the faintest alpha you can save is enough). `loop: false` plays once and stays on the last frame, timed from when the server started, so most people only see the last frame. Use it for an icon that should settle, like a bar that ends full. ## Coming from Nexo or Oraxen Their glyph files load as they are from `glyphs/`. See [Moving from Nexo and Oraxen](/rp-engine/nexo-oraxen). --- Source: https://resourcepack.ai/docs/rp-engine/ids # IDs and namespaces Everything RP Engine holds (an item, a sound, a model, a dialog) has one ID. You use it in commands (`/rp give mypack:ruby`), in other plugins' configs and in the API. It is written like a Minecraft resource location (`namespace:path`): ``` mypack:ruby mypack:furniture/chair ``` Lowercase `a-z`, digits and `_ . - /` (no `/` in the namespace). An uppercase letter is refused at load rather than lowercased, because the client would treat `MyPack` and `mypack` as two different things. ## The ID is the reference The ID goes straight into the item's model reference, and the file paths follow from it: ``` mypack:ruby → assets/mypack/items/ruby.json the item definition → assets/mypack/models/item/ruby.json the model → assets/mypack/textures/item/ruby.png yours ``` Only the texture is yours to ship. The other two files are generated. Before Minecraft 1.21.4 From 1.21.4 the game picks an item's model by name, so nothing is allocated and two packs from different people work side by side with nothing to configure. Before 1.21.4 the game picks a model by number. RP Engine allocates the numbers for you and keeps them in `plugins/RPEngine/model-numbers.json`. Never edit or delete that file, and expect that packs from two sources can clash. [Minecraft versions](/rp-engine/versions#below-1214-items-are-numbered) has the detail. ## Namespaces The namespace is the folder name under `content/`, and the path is the key in a definition file. `ruby:` in `content/mypack/items/gems.yml` is `mypack:ruby`. There is nothing to declare or register. Shader objects and dialogs from a Studio pack have the namespace `studio`, as in `/rp shader studio:my_hud`. Two packs collide only if they use the same folder name, and that is caught at load with both sources named. ## Reserved `minecraft` and `realms` are refused. Content there would point at vanilla's own assets. To replace vanilla art, use [`overrides/`](/rp-engine/content#assets-and-overrides) instead. ## Store IDs, never what they resolve to When another plugin's config refers to RP Engine content, write the ID. An ID never changes. What it resolves to (a model path, a character) is worked out at build time and can move when other content changes. [Icons](/rp-engine/icons) are the case that bites: they are given characters in ID order, so adding one shifts every icon after it. A config that saved the character instead of the ID then shows a different picture. Use the [`%rpengine_icon_...%` placeholder](/rp-engine/placeholderapi#asking-a-question) instead. --- Source: https://resourcepack.ai/docs/rp-engine/install # Installing RP Engine is one jar. You put it in `plugins/`, start the server, and players are sent its resource pack when they join. There is nothing else to set up. ## What your server needs - **Spigot, Paper or Folia**, on **Minecraft 1.19.4 or newer**. Folia uses the same jar. - **Java 17 or newer.** Everything works on a current server. Older versions lose a few features (one pack at a time below 1.20.3, no dialogs below 1.21.6, and so on), and the plugin prints exactly which ones at startup. [Minecraft versions](/rp-engine/versions) has the full list. ## Putting it on your server Get the jar That link always points at the current release, so it works in a startup script or a Docker build too. Drop it in Put `RPEngine.jar` in your server's `plugins/` folder and start the server. Look at what it made ``` plugins/RPEngine/ config.yml content/ ← your packs go here output/ ← the built packs, rebuilt on every reload ``` Join You are asked to accept the server's resource pack. That is RP Engine's. By default the pack is uploaded to ResourcePack AI's free pack host and players download it from there, so no port has to be opened and it works behind Velocity or BungeeCord. To serve it from your own machine instead, see [Serving the pack](/rp-engine/config#serving-the-pack). You do not set a pack format number. The plugin reads your server's version and writes the right one itself. ## Your first item Make a pack A pack is a folder in `content/`. Its name, here `mypack`, becomes the first half of every ID in it. ``` content/mypack/ pack.yml items/gems.yml assets/textures/item/ruby.png ``` Make it a new folder of its own. A resource pack you already have (one with `pack.mcmeta` in it, like a Studio export) is not a content pack, and `.yml` files inside it are never read. `pack.yml` can be as short as a name: ```yaml name: My Pack ``` Describe the item `items/gems.yml`: ```yaml ruby: material: DIAMOND name: "&cRuby" ``` That is `mypack:ruby`: the folder name, then the key. Its texture is found from the ID, at `assets/textures/item/ruby.png`, with nothing pointing at it. Reload and take one ``` /rp reload /rp give mypack:ruby ``` Everybody online is sent the new pack. If the item shows as a purple-and-black square, the texture is not where the ID says it should be. `/rp reload` names every missing file in the console; [the content folder](/rp-engine/content#if-the-console-warns-you) explains each warning. ## Already have a pack? An exported [Studio](https://studio.resourcepack.ai) pack or any other resource pack `.zip` goes straight into `content/`: drop it in and run `/rp reload`. See [Adding a resource pack](/rp-engine/resource-packs). ## Where to go next The content folder Everything a pack can contain, and where it goes. Items 3D models, borrowed models, and gating one by permission. --- Source: https://resourcepack.ai/docs/rp-engine/items # Items A custom item is a vanilla item with your own name, texture or 3D model on it. Because it is a real vanilla item underneath, it stacks, burns in lava, goes in a hopper, and every other plugin sees an ordinary item. Furniture, vehicles and armour all start as items. Items are written in YAML files in the `items/` folder of a content pack: a folder in `plugins/RPEngine/content/` with a `pack.yml` in it (see [the content folder](/rp-engine/content)). One file can hold as many items as you like. For an item `ruby` in a pack called `mypack`: ``` plugins/RPEngine/content/ mypack/ ← the pack, and the first half of its IDs pack.yml ← required, can be just: name: My Pack items/gems.yml ← the item assets/textures/item/ruby.png ← its picture ``` Not inside a resource pack A folder with `pack.mcmeta` and `assets/` in it, such as a pack exported from Studio, is a resource pack. RP Engine adds it to the pack as art and never reads `.yml` files from it, even in its `assets/minecraft/items/` folder. Make your own content pack beside it as shown above. ![Custom items in an inventory](/images/items.webp) ```yaml # items/gems.yml ruby: material: DIAMOND # required: the vanilla item underneath name: "&cRuby" lore: ["&7Warm to the touch."] texture: item/ruby # defaults to item/ stack: 16 # largest stack glow: true # the enchanted shimmer, without an enchantment unbreakable: true ``` `material` decides how the item behaves, so pick it for that. A `PAPER` ruby does nothing when used; a `DIAMOND_SWORD` one swings like a sword. Names and lore take `&` colour codes. `/rp give mypack:ruby` gives you one. `/rp items` lists them all, and `/rp item menu` opens them in a chest to take from. `stack` and `glow` need Minecraft 1.20.5 or newer; on an older server they are ignored with a console warning. ## The texture With no `texture:` and no `model:`, `mypack:ruby` uses `assets/textures/item/ruby.png`. `texture:` points somewhere else, for example to let two items share one picture. It can also be a full resource location, such as `minecraft:item/custom/ruby`. A missing texture is a build warning that names the path it looked for. An item on a sword, axe, pickaxe, shovel or hoe (or a stick, rod or mace) is held at an angle like the vanilla one; anything else is held flat. Vanilla draws these with the handle in the bottom left and the tip in the top right. A picture drawn the other way round (tip top left, handle bottom right) is mirrored for you, so it still points forward in the hand. Both need RP Engine 0.2.77 or newer. On an older version every flat item is held flat: write the model in as shown under [3D items](#3d-items), with `parent: minecraft:item/handheld`, and draw the picture the vanilla way. ### Choosing how it's held When the material's way is wrong for your item (a flag on paper that should be held like a staff, a wand on a stick that should sit upright), say how with `held:`: | `held:` | Held like | | --- | --- | | `item` | Paper: flat and upright | | `tool` | A sword: at an angle, the bottom left of the picture in the hand | | `rod` | A fishing rod: the tool angle turned the other way | ```yaml flag: material: PAPER texture: item/flag held: rod ``` With `held:` set, the picture is used exactly as drawn and never mirrored. Needs RP Engine 0.2.80 or newer. Items brought across from Nexo or Oraxen keep the way their `parent_model` held them. ## 3D items Point `model:` at a Blockbench file in `assets/models/`: ```yaml sword: material: IRON_SWORD model: sword # assets/models/sword.bbmodel ``` Two file types work: - **`sword.bbmodel`**: the project Blockbench saves. Its textures are inside it, so the model is one file. Use this one. - **`sword.json`**: a Java model exported from Blockbench, with its PNGs beside it. It has no bones or keyframes, so [an animated model](/rp-engine/animation) must be the `.bbmodel`. The game's models only allow a cube to be rotated on one axis, by -45, -22.5, 0, 22.5 or 45 degrees, so other rotations are snapped to the nearest of those. Meshes are left out: convert them to cubes first. `model:` can also name a model by resource location (`model: minecraft:item/custom/lamp`), or be written into the item directly: ```yaml pick: material: IRON_PICKAXE model: parent: minecraft:item/handheld textures: { layer0: mypack:item/pick } ``` ### A different model in first person `first-person:` is a second model, written any of the same ways as `model:`, that is drawn only in the holder's own first-person view. Everyone else, and the inventory, see `model:`. It suits an aimed gun, where the sights should fill the view: ```yaml rifle_aimed: material: PAPER model: rifle first-person: rifle_sights ``` Needs Minecraft 1.21.4 or newer. On an older server the normal model is used in first person too, with a warning. ### An icon in the inventory `gui:` is how the item looks in an inventory slot: the hotbar, a chest, a creative tab. A model made to be seen in the world, like a vehicle or a chair, is hard to read shrunk to sixteen pixels, so give it an icon instead. Write a model the same ways as `model:`, or `{texture: ...}` for a flat icon (a bare name is looked for in `textures/item/`): ```yaml red_kart: material: PAPER model: red_kart gui: {texture: red_kart_icon} ``` Everywhere else (in a hand, on the ground, placed) the item keeps its model. Needs Minecraft 1.21.4 or newer, like `first-person:`. It works on 3D armour pieces too: an item with `armor3d:` and `gui:` shows the icon in the slot and the 3D piece everywhere else, on the player included. ### Bows and crossbows: drawing back and loaded A custom bow or crossbow can change look as it is drawn and when it is loaded, like the vanilla ones. `pull:` gives the item a look for each stage of being drawn, the way a vanilla bow has three. The first is shown the moment the player starts drawing, and the item goes back to its own look when they let go: ```yaml longbow: material: BOW model: longbow pull: [longbow_pull_0, longbow_pull_1, longbow_pull_2] ``` Each entry is the same kind of thing as the item's own look: a model when the item has a `model:`, a texture when it is a flat sprite (a bare name such as `longbow_pull_0` is `textures/item/longbow_pull_0.png`). To mix them, or to say when each stage starts, write each one out: ```yaml pull: - { at: 0, model: longbow_pull_0 } - { at: 0.65, texture: item/longbow_pull_1 } - { at: 0.9, model: longbow_pull_2 } ``` `at:` is how far drawn the stage begins. A bow is fully drawn after one second, so for a bow it reads as a fraction; a crossbow's is the fraction of its loading time, so Quick Charge speeds the stages up as it does vanilla's. Leave it out and three stages on a bow or crossbow use vanilla's own timings, and any other number of stages is spread evenly. A crossbow also has a loaded look: ```yaml repeater: material: CROSSBOW model: repeater pull: [repeater_pull_0, repeater_pull_1, repeater_pull_2] charged: repeater_arrow # loaded with an arrow charged-firework: repeater_rocket # loaded with a firework; optional ``` Without `charged-firework:` a firework shows the `charged:` look too. All of it is drawn by the player's own game, so everybody watching sees the draw and the server sends nothing while it happens. On Minecraft 1.21.4 or newer any item a player can hold in use (a bow, a crossbow, a trident, a shield) can have `pull:` stages. On an older server only an item built on `BOW` or `CROSSBOW` can, and anything else keeps its own look, with a warning. Bedrock players see the item's own look throughout. Needs RP Engine 0.2.25 or newer. Drawing, loading, first person and the inventory icon are the only things an item's look can follow. For an item that changes for another reason (a lamp switched on, a Christmas version), make a second item; a placed piece can use [states](/rp-engine/furniture#states-lamps-doors-and-screens) instead. ## Tools made of parts An item can be built out of parts that a player chooses, like a pickaxe made of a handle and a head. You make one small item per part, and RP Engine draws the tool out of whichever parts it holds. Four handles and four heads are eight textures, not sixteen whole pickaxes. ```yaml oak_handle: material: STICK birch_handle: material: STICK iron_head: material: PAPER gold_head: material: PAPER pickaxe: material: IRON_PICKAXE name: Pickaxe parts: handle: [oak_handle, birch_handle] head: [iron_head, gold_head] ``` - Each slot under `parts:` lists the items that can fill it. A name without a namespace is in the item's own pack. - Slots are drawn in the order you write them, so a later slot is drawn over an earlier one where they overlap. Draw each part's texture in the place it takes in the finished tool, on a transparent background. - A pickaxe that has not been given any parts (from `/rp give`, say) holds the first option in each slot: here, an oak handle and an iron head. - The pickaxe needs no texture or model of its own. To let players put one together, write a [recipe](/rp-engine/recipes#tools-made-of-parts) whose ingredients are the parts. Plugins can set the parts themselves through the [API](/rp-engine/api). Minecraft 1.21.4 or newer Drawing an item out of several models arrived in 1.21.4. On an older server the item draws as its own texture or model whatever parts it holds, and the parts are still kept on every stack. ## A designed tooltip A [Tooltip](/tooltips) made in Studio is a picture shown in place of the item's hover box. `tooltip:` puts one on an item: ```yaml legend_blade: material: DIAMOND_SWORD model: legend_blade name: "&6Legend Blade" # shown only where the tooltip can't be tooltip: legendary # or studio:legendary ``` The id is the Tooltip's id in Studio. The Studio pack it comes from has to be on the server: synced to it, published to it, or exported from Studio and dropped into the content folder. Every stack of the item RP Engine makes then shows the picture. - **The tooltip replaces the item's own `name:` and `lore:`.** The item has no name of its own while it wears one, so nothing is written over the picture or above the hotbar. Keep `name:` and `lore:` anyway: they are what the item shows when the tooltip can't be used. - The tooltip hides the lines the game adds under a hover box (attributes, enchantments and so on), so `flags:` makes no difference to such an item. - If no Studio pack on the server has that Tooltip, the item shows its own name and lore and the console says so once, naming the item and the id. - A stack already in somebody's inventory keeps what it was made with. Its picture comes from the pack, so a redrawn Tooltip shows on it straight away, but if the Tooltip changes height, starts or stops moving, or gains or loses its shimmer, give a fresh one. - A [recipe](/rp-engine/recipes)'s result is made when content loads. If the Tooltip comes from a published pack, which arrives a moment after the server starts, crafted items wear it from the next `/rp reload`. Needs Minecraft 1.21.5 or newer and RP Engine 0.2.78 or newer. On an older server `tooltip:` is ignored with a console warning, and the item shows its own name and lore. Works on Spigot and Paper. ## Borrowing another item's model ```yaml ruby_sword: material: IRON_SWORD copy-model: mypack:sword ``` The item wears `mypack:sword`'s model without a copy of the files, which suits a set of items that look alike and behave differently. ## Permissions ```yaml wand: material: STICK permission: mypack.wand ``` Checked when the item is **used** (clicked, or placed if it is furniture), not when it is given or held. A player without it is told "You cannot use that." See [Permissions](/rp-engine/permissions#letting-players-use-your-items). ## The creative inventory Custom items don't appear in the creative inventory's tabs or its search. The game builds those from its own list of vanilla items, and a server can't add to them. To pick custom items from a menu, run `/rp item menu`: a chest of every custom item, click for one and shift-click for a stack. It needs `rpengine.item`, which only ops have unless you grant it. A player in creative mode can copy any item they can see in their own inventory, a custom one included, and RP Engine doesn't prevent it. Keep creative mode from players who mustn't have your items, rather than relying on them not finding one. ## Where to go next Stats and components Damage, durability, enchantments, food, and flags like `hat`. Actions Making an item do something when it is used. Armour Any item worn on a body, with its own art. Placing a model A `place:` block turns an item into something you can put down. --- Source: https://resourcepack.ai/docs/rp-engine/itemsadder # Moving from ItemsAdder RP Engine reads ItemsAdder's config files as they are, so you can move an ItemsAdder pack (including one bought on a marketplace) to RP Engine without converting anything. 1. Copy the pack's folder out of ItemsAdder's `contents/` into `plugins/RPEngine/content/`, everything in it included: `configs/`, `textures/`, `models/`, `resourcepack/`. 2. You do not need a `pack.yml` (RP Engine's own pack file). Leave one out. 3. Start the server, or run `/rp reload`, and read the console for warnings. ``` plugins/RPEngine/content/ my_content/ ← straight out of ItemsAdder's contents/ configs/ ← read at any depth items.yml textures/ ← older layout: art at the pack root models/ resourcepack/ ← ItemsAdder 4 layout assets/my_content/ textures/ models/ ``` Both layouts work, and art kept in folders of its own (`textures//` rather than `textures/item/`) is found too. There is nothing to turn on: a file is recognised by its own shape (an `info:` block beside `items:`, `font_images:` or `recipes:`). So one of their files also works inside a pack of yours, which is a handy way to move over a piece at a time. The folder's name becomes the **namespace**: the first half of every item's ID, as in `my_content:ruby`. Keep the folder name ItemsAdder used and your existing IDs keep working. ## What comes across | ItemsAdder | RP Engine | |---|---| | `items.` | an [item](/rp-engine/items) | | `resource.material` | `material` | | `resource.textures` / `texture` | `texture`: the first one, since a flat item has one picture | | `resource.model_path` | `model` | | `display_name` or `name` | `name` (ItemsAdder 4.0.9 renamed it, so both are read) | | `lore`, `permission` | the same | | `enchants`, `attribute_modifiers.mainhand` | `enchantments`, [`attributes`](/rp-engine/stats) | | `durability.max_durability`, `unbreakable` | `durability`, `unbreakable` | | `max_stack_size` | `stack` | | `equipment.id` or `specific_properties.armor.custom_armor` | [`armor`](/rp-engine/armour), worn with that set's layer art | | `equipments`, `armors_rendering`, `legacy_armor_renderings` | the layer art, read from any file in the pack | | `equipment` with no `id`, on the head | `hat`, so a 3D helmet shows its model | | `behaviours.liquid_bucket` | [`liquid`](/rp-engine/liquids) | | `behaviours.furniture` | [`place:`](/rp-engine/models), with its light, solidity and seat | | `blocks.` | a [custom block](/rp-engine/blocks), with its model, hardness, light and tool | | `behaviours.block` (or `specific_properties.block`) on an item | a [custom block](/rp-engine/blocks), with its name, lore, model (or the cube generated from its textures), hardness, tool, `light_level` and place sound | | `placed_model.type` `REAL_NOTE` · `REAL` · `REAL_WIRE` · `REAL_TRANSPARENT` | a note block · `base: mushroom_stem` · a [plant](/rp-engine/blocks#plants) on cut tripwire · `shape: grate`, the see-through full block | | `directional_mode` `LOG` · `FURNACE` · `DROPPER` / `ALL` | [`rotate:`](/rp-engine/blocks#turning-and-states) `axis` · `horizontal` · `all`. Its `_` items are each direction's look, and are not placed as blocks of their own | | `custom_variants`, with `weight` | [`random:`](/rp-engine/blocks#turning-and-states), a look picked as each is placed | | `no_explosion` | `blast-resistant` | | a placed block's `interact` event with `replace_block` (`to`) | [`click-into`](/rp-engine/blocks#what-else-a-block-does), so on/off pairs switch | | `loots.blocks.`, in any file | the block's `drop`, when the table's first item is the pack's own and certain | | `item_flags` | [`flags`](/rp-engine/stats) | | `events` | [actions](/rp-engine/actions), below | | `font_images.` | an [icon](/rp-engine/icons) | | `sounds.`, with its subtitle, volume, pitch and stream | a [sound](/rp-engine/sounds), the subtitle looked up in your `minecraft_lang_overwrite` when it is a key | | a `sounds.json` in `resourcepack/assets//`, from before 4.0.12 | a [sound](/rp-engine/sounds) per entry | | `recipes.crafting_table`, `cooking`, `campfire_cooking`, `stonecutter` | [recipes](/rp-engine/recipes): shaped, the cookers (one each for a recipe with several `machines`), campfire and stonecutting | | `recipes.smithing` | a `smithing` recipe | | `recipes.anvil_repair` | an `anvil` repair, a quarter of full durability per ingredient, as theirs | | `recipes.brewing` (from the ItemsAdderAdditions add-on) | a `brewing` recipe, which needs Paper; `minecraft:awkward_potion` is `potion/awkward` | | `enabled: false` | skipped, as it is there | A recipe's bare lowercase ID (`base: my_sword`) is the file's own namespace, as ItemsAdder reads it. A recipe's `permission` is not carried across: RP Engine recipes are open to everyone. ## Events become actions | ItemsAdder event | RP Engine trigger | |---|---| | `interact.right`, `interact.left` (a bare `interact` is both) | `right_click`, `left_click` | | `attack`, `drop`, `pickup`, `block_break` | the same | | `eat`, `drink` | `consume` | | `item_break` | `break` | | `bow_shot` | `shoot` | | `placed_block` / `placed_furniture`: `interact`, `break`, `place` | the block's or furniture's own [`interact`, `remove`, `place`](/rp-engine/actions#the-thing-in-the-world) | Inside an event, `play_sound`, `execute_commands` (`as_console: true` runs as the console, otherwise as the player), `potion_effect`, `give_item`, `decrement_amount`, `cancel`, and ItemsAdderAdditions' `message` and `actionbar` come across, in order. `play_particle` and `shoot_particle` are a [`particle`](/rp-engine/actions#steps) step, a shot particle drawn as a puff where it happens. `{player}` means the same thing in both plugins. A permission that every action in an event asks for becomes one `permission` step at its front. ## What does not Each of these is a warning naming the ID when the pack loads, so nothing is dropped silently. A world of blocks does not come across Block *definitions* translate. The blocks already standing in a world do not: the vanilla state each one hides in (a note block, a mushroom, a tripwire or a chorus plant) was allocated by ItemsAdder against its own numbering, so this engine reads them as whatever it gave that state. The pack migrates; the world has to be rebuilt or remapped by hand. The pool is also [smaller](/rp-engine/blocks): 49 blocks on the note block base rather than ItemsAdder's 800, plus 63 on `mushroom_stem`. A pack with hundreds of blocks will not fit as it stands. **Their entities** do not translate. Write them as [`entities/`](/rp-engine/entities) definitions, which are short. **Recipe groups other than the ones above** are skipped by name. **Events and actions with nothing to land on**: holding, wearing, fishing, a sneaking click, guns and books have no trigger here; damage and dropping experience have no step. An action with a `delay`, or with a permission only some of its event's actions share, is skipped too, since a step runs when its trigger does and a permission step stops everything after it. The rest of the event still comes across. **Blocks drawn with an entity**: a `TILE` or `FIRE` `placed_model.type` draws with a spawner's or fire's entity, which RP Engine blocks do not, so it comes across as a full block. A [placed model](/rp-engine/models) draws any shape. **Loot by chance**, and mob and fishing loot. A block gives back one thing, so a table that might drop its item leaves the block dropping itself, and says so. **Some of a sound.** A sound that picks one of several files at random keeps the first, because an RP Engine sound plays one file, and `weight`, `attenuation_distance`, `preload` and `jukebox` have no equivalent here. Your audio stays where it is: their `sounds/` folder and resource pack folder are both packed where an RP Engine sound looks. ## If the console warns **`info.namespace says galaxy_set but the folder is galaxyset, and the folder wins`** The pack's configs declare one namespace and its folder has another name (a pack is often unzipped into a folder named differently). The items load as `galaxyset:...`, and their models and textures are still found under `resourcepack/assets/galaxy_set/`, so they look right. If other plugins, shops or commands name the items as `galaxy_set:...`, rename the folder to `galaxy_set` and `/rp reload`. Otherwise the warning is harmless. **An item shows the missing texture (black and pink)** Check the warning above it for the path RP Engine looked at. The usual causes are a folder renamed after the pack was made (see above), or a pack whose art was left out when it was copied. Copy the whole pack folder, `resourcepack/` included. ## Good to know **Their art can stay where it is.** ItemsAdder keeps art at the pack root or in `resourcepack/assets/`, and RP Engine reads both, so `textures/item/ruby.png` and `models/lamp.json` need no moving. For new content you write beside it, use `assets/`, as the [content folder](/rp-engine/content) page describes. **Armour art stays where it is.** A set's `layer_1` and `layer_2` are exactly the two pictures [vanilla's equipment path](/rp-engine/armour) draws (body and leggings), so the build serves them there for you. That needs Minecraft 1.21.4; on an older server the armour is still worn but draws with vanilla art, and the build names every piece that will. What does not come across from a set, each a warning naming the item: an **animated** layer, which is a strip of frames a worn layer cannot play (save one frame as `assets/textures/entity/equipment/humanoid/.png`, or `humanoid_leggings/` for legs); a `use_color` **tint** and **emissive** layers, which needed ItemsAdder's shaders; and **colour-only** armour, which has no art and is worn as plain leather. --- Source: https://resourcepack.ai/docs/rp-engine/liquids # Liquids A custom liquid is a pool of acid, a healing spring or a cursed lake: an area of water or lava that does something to whoever is in it, and can have its own colour. What a custom liquid is Minecraft only has water and lava, and a server can't add a third fluid. A custom liquid is real water or lava with your rules applied inside a box you mark out. It behaves like a fluid because it is one: you swim in it, boats float, it flows, and other plugins see water. What makes it acid is the box, not the blocks. ```yaml # liquids/acid.yml acid: base: water # water | lava color: "#3FBF4A" # optional; keep the quotes effect: POISON amplifier: 1 # 0 is level I, 1 is level II damage: 1.0 # per second fireproof: false ``` | Field | Default | What it does | |---|---|---| | `base` | `water` | `water` or `lava`: what it really is | | `color` | none (the water keeps its colour) | Hex or a dye name. See [Colour](#colour) | | `effect` | none | A potion effect given while inside | | `amplifier` | 0 | The effect's level, counting from 0 (0 to 255) | | `damage` | 0 | Damage per second, on top of anything lava already does (0 to 100) | | `fireproof` | `false` | Whether a lava-based liquid stops burning you | | `tags` | none | A list of labels, for your own plugin to read (`LiquidInfo.tags()`) | Put the YAML in a `liquids/` folder of your [content folder](/rp-engine/content) (here `mypack`) and run `/rp reload`. ## Making a pool There are two ways, and they make the same thing. ### Mark out water that's already there These commands need you in game, and the `rpengine.liquid` permission. ``` /rp liquid corner stand at one corner /rp liquid fill mypack:acid stand at the opposite corner /rp liquid clear remove the pool you're standing in /rp liquid list every pool, by world ``` The two corners make a box, and everything inside it that is the right fluid follows the liquid's rules. Lakes are rarely rectangular, so use several boxes. Where boxes overlap, the oldest pool wins. ### Build it with a bucket ```yaml # items/acid_bucket.yml acid_bucket: material: BUCKET liquid: mypack:acid ``` Right-click a block and it places one source block and makes that spot part of the liquid. A block placed next to a pool of the same liquid joins it, so a pond built click by click (even by two people from opposite ends) ends up as one pool. It's a real source block, so it flows. Water that runs outside the pool is plain water, so dig a basin as you would for vanilla water. ## Colour `color:` takes `"#3FBF4A"`, `0x3FBF4A`, `3FBF4A`, or a dye name such as `RED`, `LIGHT_BLUE` or `LIME`. Quote the `#` form: without quotes, YAML treats it as a comment and you get no colour and no error. The game can only tint water by biome, so RP Engine paints the pool with a biome of its own. That has some side effects: - **A new colour needs a server restart.** The biomes go into a datapack in your world folder (`datapacks/rpengine_liquids`) and the server only reads them at startup. Until then the pool works but is the wrong colour. - **It bleeds a little.** Biomes are stored in 4×4×4 cells, so there's a rim of tinted water round the pool. - **Small pools look paler.** The game blends biome colours over several blocks, so a pool under about 8 blocks across never reaches its full colour, and players with a high biome blend setting see even less. - **Colours come out muted**, because the tint is multiplied by vanilla's dark water texture. A pack can ship a paler `water_still` texture to get brighter colours, but that makes every ocean on the server pale too, so RP Engine won't do it for you. Clearing a pool paints it back to the biome that was there when it was made (one biome for the whole box). ## Doing more than an effect `effect` and `damage` are applied every second. For anything else (a title, a sound, a quest step), listen for [`PlayerLiquidEvent`](/rp-engine/api#events), which fires when someone goes into a pool and again when they come out. --- Source: https://resourcepack.ai/docs/rp-engine/mobs # Putting a model on a mob Any entity on the server can wear one of your models: a MythicMobs boss, a Citizens NPC, a shopkeeper, a mob another plugin owns. Look at it and run: ``` /rp bind mypack:golem put the model on the mob you are looking at /rp unbind take it off again ``` Look at it from within 12 blocks. Both commands are for operators by default (`rpengine.bind`, `rpengine.unbind`). Putting a model on another **player** also needs `rpengine.bind.others`. The entity is not replaced. It keeps its AI, loot, health, hitbox and UUID, and every plugin that knows about it still has the same entity. Only its vanilla body is made invisible, and `/rp unbind` brings it back. To spawn a new mob that comes with a model, use [custom entities](/rp-engine/entities) from your content folder, or a [Mob made in Studio](/mobs). ## Drawing the model so it fits - **Face it North** in Blockbench (the -Z side is the front), as for Model Engine. A model drawn facing South walks backwards. - **Its bottom stands on the ground** under the mob, whatever the mob's size. ## The model is an item ID Use the same ID a [`place:`](/rp-engine/models) block uses, so one model can stand in the world and be worn by a mob without being written twice. If the model animates, the worn copy animates and faces wherever its mob faces. [Bones that do something](/rp-engine/bones) work here: `h_` heads track what the mob is fighting, `b_` hitboxes let it be hit where you aimed, `p_` and `mount` bones are seats, and `tag_` puts its name somewhere sensible. ## Playing animations A worn model has no clicks to react to, so whatever controls the mob decides when it animates: a [MythicMobs skill](/rp-engine/mythicmobs) (`rpanimate`), or [your own plugin](/rp-engine/api) through `Models.animate`. ## What it costs An animated model is one display entity per moving bone, riding the mob. A ten-bone boss is eleven entities, so keep detailed rigs for bosses rather than common mobs. ## Making it stick `/rp bind` lasts as long as that entity does. A mob that is removed and respawned by the plugin that owns it comes back without the model. Use the [Citizens trait](/rp-engine/citizens) or MythicMobs' [`rpmodel` on `~onSpawn`](/rp-engine/mythicmobs) to put it back on every time. --- Source: https://resourcepack.ai/docs/rp-engine/modelengine # Moving from Model Engine Copy your `blueprints/` folder into a pack and start the server. Every `.bbmodel` in it becomes something you can give, place, spawn or bind. ``` plugins/RPEngine/content/ mypack/ blueprints/ ← straight out of Model Engine golem.bbmodel bosses/dragon.bbmodel ``` **No `pack.yml` is needed.** A folder holding nothing but Blockbench files is plainly Model Engine's (or [BetterModel's](/rp-engine/bettermodel)), so it loads as a pack named after the folder. Add a `pack.yml` when you want to say which [bundles](/rp-engine/bundles) it goes into, or anything else one says. ``` /rp give mypack:golem the item that wears it /rp bind mypack:golem put it on the mob you are looking at /rp spawn mypack:guard a mob of your own wearing one ``` **The file name is the ID.** `golem.bbmodel` is `mypack:golem`. A blueprint in a subfolder is found where it is, and the subfolder organises without reaching the ID, the same rule as every other category: `bosses/dragon.bbmodel` is `mypack:dragon`. Uppercase or spaces in a file name are refused rather than folded, and the load says which file. ## Nothing to convert A Model Engine blueprint is a Blockbench `.bbmodel` file, holding the geometry, bones and animations, and RP Engine reads `.bbmodel` files directly, from Blockbench 4 or 5. **The bone names mean the same thing**, because RP Engine uses Model Engine's naming. A rig you made or bought works without being re-authored: | Bone | What it does | |---|---| | `h_head` | Turns to look at whatever its mob is targeting | | `hi_head` | The same, and every bone under it inherits it | | `b_wing` | A [sub-hitbox](/rp-engine/bones): the mob is hit on the wing you aimed at | | `ob_wing` | The same, turning with the bone | | `p_seat1` | Somewhere to sit | | `mount` | Where the driver sits | | `tag_name` | Where a name floats | Animations come across too: a looping animation loops, and a one-shot plays when the placed piece is right-clicked. Blockbench's loop, hold and once settings are kept as authored. What each one is called is what [`/rp` and the API](/rp-engine/animation#playing-from-a-plugin) play it by. ## What is different **An item owns the model here.** In Model Engine a blueprint is a thing in its own right, spawned with `/meg`; in RP Engine every model belongs to an [item](/rp-engine/items), which is what makes one ID work as a thing you hold, a thing you [place](/rp-engine/models) and a thing a [mob wears](/rp-engine/mobs). Dropping a blueprints folder in creates that item for you: a plain one, on paper. Write your own under the same ID in `items/` if you want more than that, and yours wins; the load still mentions the clash, so a blueprint shadowed by accident does not go unnoticed. **MythicMobs mechanics have different names.** Theirs are `model`, `state` and `unmodel`; RP Engine's are `rpmodel`, `rpanimate` and `rpunmodel` (see [MythicMobs](/rp-engine/mythicmobs)). Because the names differ, a server can run both plugins while it moves over. What a .bbmodel cannot carry Meshes are dropped (convert them to cubes in Blockbench first), and a cube's rotation is snapped to one axis at -45, -22.5, 0, 22.5 or 45 degrees. Both are limits of Minecraft's model format, which Model Engine works around with its own renderer, so a rig built for that renderer may need simplifying. --- Source: https://resourcepack.ai/docs/rp-engine/models # Placing a model A placed model is furniture, decoration or a prop: a chair, a lamp, a statue. A player holds the item, right-clicks the ground, and the model appears there at its true size. Punching it picks it back up. You make one by giving an [item](/rp-engine/items) a `place:` block. The model is drawn by a **display entity** (an invisible entity whose only job is to show a model), not a block, so it can be any shape and there is no limit on how many kinds you have. ![Models you can place with RP Engine](/images/models.webp) ## Making one Put the Blockbench project and a YAML file in your pack's folder inside `plugins/RPEngine/content/` (your [content folder](/rp-engine/content)): ``` content/mypack/ items/furniture.yml assets/models/chair.bbmodel ``` ```yaml chair: material: PAPER model: chair # assets/models/chair.bbmodel name: "&eOak Chair" place: facing: cardinal # cardinal | diagonal | free | fixed scale: 1.0 solid: false # true gives it something to walk into vehicle-collision: true # false lets vehicles drive through it seat: 0.5 # sit on it, this far above its base. 0 is no seat light: 0 # 0-15, what it gives off surface: floor # floor | wall | ceiling | any drop: mypack:shard # what breaking it gives back. Default: itself random: # each one put down a little different rotation: 180 # degrees either side of its facing. 180 is any way rotation-step: 90 # optional: turn in whole steps scale: [0.8, 1.2] # or 0.8-1.2: a size between the two permission: mypack.chair ``` Run `/rp reload`, then `/rp give mypack:chair` to get the item. Right-click the ground to place it, and punch it to take it back. Breaking it in creative mode gives nothing back. The item and the placed model share one ID (`mypack:chair`). Every key under `place:` is optional: `place: {}` is a model that just stands there. ## How big it is A placed model is the size the Blockbench file says it is: 16 model units to the block, so a model built to y=32 stands two blocks tall. If a lamp looks a block tall when you built it three, check the cube coordinates in the model. `scale:` multiplies the size, for when you want the same model in two sizes. ## Making each copy a little different `random:` gives every copy a player puts down a turn and a size of its own, so decorations placed in a row don't all look the same. Needs RP Engine 0.2.57. | Key | What it does | |---|---| | `rotation` | Degrees either side of the way `facing:` would have turned it, 0 to 180. 180 is any direction | | `rotation-step` | Turns only in whole steps of this many degrees. `90` keeps a boxy piece on the grid, `45` gives eight ways. Leave it out for any angle | | `scale` | Two numbers, `[0.8, 1.2]` or `0.8-1.2`: a multiplier picked between them, on top of `scale:`. 0.1 to 10 | Each copy rolls once, when it's placed, and keeps that turn and size for good, through restarts too. The final size is kept between 0.125 and 8 times the model's own. A plugin placing a model through `Models.place` gets exactly what it asked for, with nothing random. A model sent from Studio can carry the same settings, set on its page there. ## Which way it faces | `facing:` | How it turns | |---|---| | `cardinal` | North, east, south or west, like a placed furnace. The default | | `diagonal` | Eight directions | | `free` | Exactly the way you were looking | | `fixed` | Always the same way, for something with no front | ## What players can hit and walk into The hitbox (what you can punch) is measured off the model, so a two-block statue can be hit anywhere you can see it. `width:` and `height:`, in blocks, override it. A display entity has no collision, so players walk straight through a placed model. `solid: true` puts an invisible barrier block in the model's own block space and removes it when the model is broken. That suits a bench, not a rug. The barrier is one block, whatever shape the model is. ## Whether vehicles drive through it `vehicle-collision` decides whether [vehicles](/rp-engine/vehicles) are stopped by the model. It is on by default and separate from `solid:`, which is about players on foot. A vehicle is tested against the model's real cubes, not a box round them, and no blocks are placed for it. You can drive a go-kart between the legs of a table or under an archway, and a fence stops you along its whole length. Any placement angle works. - Turned cubes keep their angle, so a turned slab is a **ramp** a vehicle drives up. - Anything up to a block high is climbed like a kerb, and stairs built from stacked cubes are climbed a tread at a time. - A piece a vehicle can climb also holds it up, so a row of platform models is a bridge. Set `vehicle-collision: false` for things that should have no effect at all: a road marking, a manhole cover, a decal. ## Seats, light, surfaces and drops `seat:`, `light:`, `surface:` and `drop:` are covered on [Seats, light and surfaces](/rp-engine/placement-options). ## Furniture that does something A piece can also be a container, a jukebox, a furnace, a lamp or door a click switches, a sofa that joins the pieces beside it, or something that grows into another piece over time: ```yaml place: storage: { type: chest, rows: 3 } jukebox: true furnace: true states: - { model: mypack:lamp_on, light: 15 } connects: true grow: { into: mypack:rose_stage2, after: 2m } ``` See [Working furniture](/rp-engine/furniture) for each of them, and for which one a click goes to when a piece is several at once. ## Animation If the `.bbmodel` has keyframes in it, the piece moves. See [Animation](/rp-engine/animation). Bones can also carry hitboxes and nametags; see [Bones that do something](/rp-engine/bones). ## Who may place what - **`permission:`** on the item decides who may use it, which includes placing it. Without one, anybody holding it may. - **WorldGuard**: the `rpengine-place` region flag allows or denies placing and breaking models in a region. See [WorldGuard](/rp-engine/worldguard). - **`ModelPlaceEvent`** is for any other rule, from your own plugin. Cancel it and the model is not placed and the item is not used up. See [the API](/rp-engine/api). Placing never replaces a block: the space has to be empty. Right-clicking a chest, door or other block you can use opens it as normal; sneak to place against it. ## After a restart, or when a model is removed from the pack A placed model is saved with the chunk it stands in, not in a separate file, so it survives a restart and moves with a world you copy. If a pack stops declaring a model, everything already placed stays where it is with no art until the pack declares it again. `/rp models` lists the models around you and marks these orphans, and `/rp purge` removes the orphans and nothing else. --- Source: https://resourcepack.ai/docs/rp-engine/music # Music Give your server its own soundtrack. A piece of music is a playlist of your [sounds](/rp-engine/sounds). It plays to each player while they are somewhere it belongs, like a lobby world, a WorldGuard region or a box you mark out, or whenever a command or plugin starts it. Minecraft's own music is kept quiet while yours plays. ```yaml # music/lobby.yml lobby: tracks: [theme, calm] # sounds from sounds/. A bare name is this pack's shuffle: false loop: true # start again after the last track gap: 2 # seconds of silence between tracks vanilla-music: false # true lets Minecraft's own music play over it priority: 0 # the higher wins where two places overlap where: worlds: [lobby] regions: [spawn] # WorldGuard regions areas: - { world: world, from: [0, 0, 0], to: [100, 255, 100] } ``` | Field | Default | What it does | |---|---|---| | `tracks` | required | The sounds to play, in order. `theme` means this pack's `theme`; `otherpack:theme` names another's | | `shuffle` | `false` | Play them in a random order, a new one each time round. A track never plays twice in a row | | `loop` | `true` | After the last track, start again. `false` plays them once and falls silent | | `gap` | 1 | Seconds of silence between tracks (0 to 600) | | `vanilla-music` | `false` | Let Minecraft's own soundtrack play over yours | | `priority` | 0 | Where two pieces' places overlap, the higher one plays. A tie goes to the id that sorts first | | `where` | none | Where it plays by itself: any of `worlds`, `regions` and `areas`. Leave it out and it only plays when started | An area is a box of whole blocks with both corners inside it. Regions need [WorldGuard](https://enginehub.org/worldguard); without it they never match. ## The tracks Each track is an ordinary sound, so declare it in `sounds/` first: ```yaml # sounds/music.yml theme: category: music # so the player's music slider controls it stream: true # anything long should stream subtitle: "Lobby music plays" ``` **Export music in stereo.** A stereo file plays the same everywhere, which is what a soundtrack wants. Mono works too: a track follows the player, so it doesn't fade as they walk. See [mono or stereo](/rp-engine/sounds#mono-or-stereo). Minecraft can't queue sounds, so RP Engine starts each track when the one before it ends. It reads how long that is from the file. A track whose length it can't find (with a console warning on load) plays once, and the music stops after it. ## What a player hears At most one piece at a time. In order: 1. What a command or plugin started for them. 2. Otherwise, the music of the place they are in. 3. Otherwise, nothing, and Minecraft's own music as usual. Walking from one place into another switches the music within half a second. Stopping music that was started brings back the music of the place you are in. Stopping a place's music keeps it quiet until you leave that place. ## Commands ``` /rp music every piece, and what is playing for you /rp music play tunes:lobby start one for yourself, from its first track /rp music play tunes:boss Steve start one for somebody else /rp music skip on to the next track /rp music stop stop it (twice to quiet the place's music too) ``` Each verb has its own permission, so you can let players stop or skip their own music without letting them start any: | Permission | Allows | |---|---| | `rpengine.music` | `/rp music`, and all three verbs below | | `rpengine.music.play` | Starting music | | `rpengine.music.stop` | Stopping music | | `rpengine.music.skip` | Skipping a track | | `rpengine.music.others` | Any of those for somebody else | All are op-only by default. ## From a plugin ```java Music music = engine.music(); music.play(player, ContentId.parse("tunes:boss").orElseThrow()); // until stopped music.skip(player); music.stop(player); music.playing(player); // the piece, if any ``` A boss fight can start its own music and stop it when the boss dies, and the player's place music takes over again. --- Source: https://resourcepack.ai/docs/rp-engine/mythicmobs # MythicMobs With MythicMobs installed, RP Engine adds three skill mechanics so a MythicMobs mob can wear one of your [models](/rp-engine/models) and animate from its skills: a boss that wears its model when it spawns, roars when it is hit, and drops it when it dies. ```yaml Skills: - rpmodel{model=mypack:golem} @self ~onSpawn - rpanimate{animation=roar} @self ~onDamaged - rpunmodel @self ~onDeath ``` There is nothing to enable. You can also go the other way: RP Engine's own [custom mobs](/rp-engine/entities) run MythicMobs' skill lines without MythicMobs installed, so a mob can move across whole. See [Porting your MythicMobs mobs](#porting-your-mythicmobs-mobs). ## The mechanics | Mechanic | What it does | |---|---| | `rpmodel{model=…;scale=…}` | Put the model on. `scale` defaults to 1 | | `rpanimate{animation=…}` | Play one by name. `animation=stop` stops | | `rpunmodel` | Take it off | Short forms work too: `m` (or `id`) for `model`, `s` for `scale`, `a` (or `anim`) for `animation`. All three act on their target, so `@self` dresses the caster and any other targeter dresses whatever it names. That is how a summoner can dress what it summons. ## Use ~onSpawn A model stays on for as long as the entity exists. Putting it on in `~onSpawn` means every mob of that type wears it, including ones that come back after a chunk reload. ## Animations come from the skill tree RP Engine's own animation [triggers](/rp-engine/animation#when-it-plays) do not fire for a model worn by a mob. Use `rpanimate` from whatever trigger suits: `~onDamaged`, `~onAttack`, a timer, a health threshold. ```yaml - rpanimate{animation=enrage} @self ~onDamaged =50% ``` ## The mob stays MythicMobs' RP Engine changes what it looks like and nothing else. Its health, damage, AI, drops and skills are all still MythicMobs'. See [Putting a model on a mob](/rp-engine/mobs). ## Porting your MythicMobs mobs RP Engine's [custom mobs](/rp-engine/entities) read MythicMobs' skill lines, drop lines, drop tables and spawners, so a mob can be moved across and MythicMobs (and Model Engine) taken off the server. Needs RP Engine 0.2.53 or newer. 1. Write the mob in `entities/` in RP Engine's shape (below), with `model:` naming its Blockbench file. 2. Copy its `Skills:` block in as it is. 3. Copy its metaskills into `skills/`, its drop tables into `drop-tables/` and its spawners into `spawners/`. Those files keep MythicMobs' own key names. 4. `/rp reload` and read the warnings: each line that can't run is named, with its file and place, and only that line is skipped. ```yaml # MythicMobs: Mobs/golem.yml GolemKing: Type: IRON_GOLEM Display: "&6Golem King" Health: 300 Damage: 12 Options: MovementSpeed: 0.2 PreventOtherDrops: true Skills: - model{mid=golem} @self ~onSpawn - skill{s=GroundSlam} @self ~onTimer:120 - state{mid=golem;s=roar} @self ~onDamaged =50% Drops: - diamond 1to3 0.5 ``` ```yaml # RP Engine: entities/golem.yml golem_king: type: IRON_GOLEM model: bosses:golem # replaces the model{mid=...} line name: "&6Golem King" health: 300 damage: 12 speed: 0.8 # a multiple of the golem's own speed, not a copied number skills: - skill{s=GroundSlam} @self ~onTimer:120 - animate{a=roar} @self ~onDamaged =50% drops: - minecraft:diamond 1to3 0.5 ``` ### What ports unchanged - **Skill lines**, as written: mechanics, `@targeters`, `~triggers`, `?conditions`, health parts and chances, with MythicMobs' names and short names. The [Skills](/rp-engine/skills) page lists every one that runs. - **Metaskills**, in their own file shape: `Cooldown`, `Conditions`, `TargetConditions`, `TriggerConditions`, `Skills`. - **Drop lines** (`diamond 1to3 0.5`, `exp 10to20`, `droptable name`, `command{c=...}`), **drop tables** with `TotalItems`, `MinItems`, `MaxItems` and conditions, and **spawners** with their own key spellings. See [Drops and spawners](/rp-engine/drops-and-spawners). - **Phases**: `=50%` fires once per mob, as in MythicMobs. ### What to change The mob file around the skills is RP Engine's, not MythicMobs' (`type`, `model`, `health`, not `Type`, `Display`, `Options`): | MythicMobs | RP Engine | |---|---| | `Type`, `Display`, `Health`, `Damage`, `Armor` | `type`, `name`, `health`, `damage`, `armor` | | `Template:` | `extends:` (`template:` and `Template:` read the same) | | `Equipment:` | `equipment:` (the list form copies across) | | `DamageModifiers:` | `damage-modifiers:` (the list form copies across) | | `Faction:` | `faction:` | | `Options.Despawn` | `despawn:` | | `Options.Invincible`, `Collidable`, `NoGravity` | `invincible:`, `collidable:`, `gravity:` | | `Options.PreventLeashing`, `PreventRenaming` | `prevent: [leash, rename]` | | `Options.MovementSpeed`, `FollowRange`, `KnockbackResistance` | `speed:` (a multiple of the type's own), `follow-range:`, `knockback-resistance:` | | `Level`, `LevelModifiers` | `level:`, `per-level:` (`LevelModifiers` reads the same) | | `KillMessages:` | `kill-messages:` | | `Mount:` | `mount:` | | `BossBar:` | `boss-bar:` | | `Drops:`, `DropTables/` | `drops:` (the line form copies across), `drop-tables/` | | `Spawners/` | `spawners/` | | `Modules.ThreatTable` | `threat-table: true` (the MythicMobs spelling reads the same) | | `Variables:` | `variables:` | | `Skills:` | `skills:` (`Skills:` reads the same) | - **Models are `model:`**, so drop Model Engine's `model{mid=...}` line. `state{mid=...;s=attack}` runs as `animate`, and RP Engine plays `idle`, `walk`, `attack` and the rest by itself from [`animations:`](/rp-engine/entities#animations), so most `state` lines can go. - **Draw the model facing North** in Blockbench, as for Model Engine, or set [`turn:`](/rp-engine/entities#facing). - **`drops:` replaces the vanilla loot**, so `PreventOtherDrops` is never needed. - **`=50%` is remembered while the server runs**, so a restart lets a phase fire once more. ### What isn't supported Each is a load warning naming the line: - variable maths and scopes other than the mob's (`variableMath`, `skill.` and `global.` variables); - `switch` and `foreach`; - custom AI goals (`AIGoalSelectors`): pick `type` for behaviour, and move it with the mechanics; - `disguise` and `onHear`; - composite conditions (`a && b`); - riding a mob as a player (`mountmodel`); - `ImmunityTables` and `Trades`; - `command{asop=true}` run as an op player. Mechanics, conditions and targeters a MythicMobs add-on gave you can be written as a plugin of your own against the [Plugin API](/rp-engine/api#skills). --- Source: https://resourcepack.ai/docs/rp-engine/nexo-oraxen # Moving from Nexo or Oraxen RP Engine reads Nexo and Oraxen config files as they are, so you can move your items, furniture, blocks, glyphs, sounds and recipes across without rewriting them. 1. Make a folder in `plugins/RPEngine/content/` for the pack, such as `my_pack/`. Its name becomes the **namespace**, the first half of every ID (`my_pack:ruby`). 2. Copy `items/`, `glyphs/`, `recipes/` and `sounds.yml` out of `plugins/Nexo/` or `plugins/Oraxen/` into it. 3. Copy the art: - **Nexo:** copy `plugins/Nexo/pack/assets/` to `my_pack/resourcepack/assets/`, every namespace in it. Models and textures you bought usually sit in `plugins/Nexo/pack/external_packs/` instead, as zips or folders: unzip each one and merge its `assets/` into the same place. - **Oraxen:** copy `pack/models/` and `pack/textures/` to `my_pack/models/` and `my_pack/textures/`. 4. Start the server, or run `/rp reload`, and read the console for warnings. ``` plugins/RPEngine/content/ my_pack/ items/ ← from Nexo/items// or Oraxen/items// glyphs/ ← from glyphs/ recipes/ ← from recipes/: Nexo's type folders or Oraxen's shaped.yml and friends sounds/ ← sounds.yml resourcepack/ assets/ ← Nexo/pack/assets/, plus each pack from external_packs/ minecraft/ / ``` A path with no namespace in a Nexo item or glyph (`model: furniture/chair`) means `assets/minecraft/`, as it does in Nexo, and a namespaced one (`shop:furniture/chair`) means that namespace's folder. There is nothing to turn on and no `pack.yml` (RP Engine's own pack file) is needed: each file is recognised by its shape. So one of their files also works **inside** a pack of yours, which is handy for moving over a piece at a time. Both plugins' current formats are read (Nexo 1.28, Oraxen 1.220), and Oraxen's older capitalised sections too. ## What comes across | Nexo / Oraxen | RP Engine | |---|---| | item id | an [item](/rp-engine/items) under the content pack's namespace | | `material`, `lore`, `unbreakable` | the same | | `itemname`, `displayname` or `customname` | `name` | | `Pack.model` | `model` | | `Pack.texture` (Nexo), `pack.textures` (Oraxen) | `texture`, the first layer | | `Components.item_model` | `model`, for Nexo items with no `Pack:` | | `Enchantments` | `enchantments` | | `AttributeModifiers`, list or map form | [`attributes`](/rp-engine/stats), with operation and slot | | `durability`, `max_damage` | `durability` | | `max_stack_size` | `stack` | | `food` | `food` | | `enchantment_glint_override: true` | `glow` | | custom armour: `equippable`, `trim_pattern`, or an id like `ruby_helmet` | [`armor`](/rp-engine/armour), worn with the set's layer art | | `Pack.CustomArmor` layers, or `ruby_armor_layer_1.png` / `_2.png` anywhere in the pack | the layer art, found the way the plugins find it | | `equippable` on the head with no `asset_id` / `model` | `hat`, so a 3D helmet shows its model | | `ItemFlags` | [`flags`](/rp-engine/stats) | | `Mechanics.commands` | [actions](/rp-engine/actions) on either click (on eating, for food), with its cooldown, permission and `one_usage` | | `Mechanics.custom` | actions, for its `CLICK`, `DROP`, `PICKUP` and `BREAK` events | | furniture or block `clickActions`, Oraxen's `events` | the piece's own [`interact`](/rp-engine/actions#the-thing-in-the-world) | | Oraxen's legacy `food`, `consumable`, `consumable_potion_effects` | `food`, and `consume` / `right_click` actions | | `soulbound` | `keep-on-death` | | Oraxen's `hat` | `hat` | | `Mechanics.furniture` | [`place:`](/rp-engine/models) | | furniture barriers | `solid: true` | | furniture interaction hitbox | `width` and `height` | | furniture seat | `seat`, all three numbers | | furniture light | `light` | | `restricted_rotation` | `facing`: 8 ways by default, 4 for `VERY_STRICT` | | `limited_placing` | `surface` | | a uniform `scale` | `scale` | | a `nexo_item` / `oraxen_item` drop | `drop` | | furniture `storage` | [`storage`](/rp-engine/furniture#storage): the same five kinds, rows, title and sounds | | furniture `jukebox` | [`jukebox`](/rp-engine/furniture#a-jukebox), with its volume, pitch and permission; Oraxen's `active_model` is `playing-model` | | furniture `door` | [a second state](/rp-engine/furniture#states-lamps-doors-and-screens): turned a quarter (or only slid, for `is_sliding`) and moved by its `open_properties` translation, not solid when open if `toggle_hitbox_on_open` says so, with its open and close sounds, and `automatic_close_delay` as `reset-after` | | Nexo's furniture `states` | one state each, wearing its item model, light, barrier and translation, with `reset_after` | | a switched light: `lights.toggleable`, Oraxen's `toggle_light` | dark as placed (or Oraxen's base level), lit as a state, wearing `toggled_model` / `toggled_item_model` | | `rotatable` | states that each turn the piece one step further: a quarter on four facings, an eighth on eight | | `evolution` (`next_stage`, `delay`, `probability`) | [`grow`](/rp-engine/furniture#growing): `into`, `after`, `chance` | | Nexo's `connectable` (`straight`, `left`, `right`, `inner`, `outer`, or a `default` they are named after) | [`connects`](/rp-engine/furniture#joining-up-sofas-and-counters), facing one of four ways | | `custom_block` (Nexo), `block` (Oraxen), the old `noteblock` | a [custom block](/rp-engine/blocks), with its model, hardness, tool, drop, light and place sound. Its shape is [below](#blocks-in-their-own-shapes) | | a block drawn by a model the plugin generates from `parent_model` and textures | the same model, generated here and written inline | | Oraxen `breaking` rules | the first rule's hardness, tool and drop | | static glyph | an [icon](/rp-engine/icons), with its height and ascent | | glyph grid (`rows`, `columns`) | one icon per cell, `_1` onwards, numbered the way `` numbers them | | reference glyph (`reference`, `index`) | an icon drawing that cell of the sheet it names, in the same file | | Oraxen `animation: {frames, fps, loop}` | an [animated icon](/rp-engine/icons#animated-icons), the whole strip | | Nexo `gif`, `frame_count` | an animated icon drawn from the GIF, `frame_count` as its frames | | glyph `placeholders`, Oraxen `chat.placeholders` | the icon's chat [`aliases`](/rp-engine/icons#more-ways-to-type-one-and-who-may) | | glyph `permission`, Oraxen `chat.permission` | the icon's `permission` | | `sounds.yml` entry | a [sound](/rp-engine/sounds), with its file, category, subtitle, volume, pitch and stream | | shaped, shapeless, furnace, blasting, smoking, campfire and stonecutting recipes | [recipes](/rp-engine/recipes), with vanilla, Nexo and Oraxen ingredients | | smithing recipes, Nexo's `trim_pattern` and `copy_components` included | `smithing` and `smithing_trim` recipes | | Nexo brewing recipes | `brewing` recipes, which need Paper | | anvil recipes: Oraxen's `base`, `addition` and `experience_cost`, Nexo's `input`, `material`, `cost` and `repair` | `anvil` recipes, a repair where there is no result | An item model such as `my_pack:item/ruby` becomes RP Engine's `item/ruby`. Nothing depends on the old plugin's CustomModelData numbers. ## Blocks in their own shapes Both plugins make a custom block by borrowing an unused state of a vanilla block, and the block's `type` says which. Each has an equivalent here: | Nexo / Oraxen `type` | RP Engine | |---|---| | `NOTEBLOCK` / `FULL` | a note block, as an ordinary [custom block](/rp-engine/blocks) | | `STRINGBLOCK` / `STRING`, the old `stringblock` | a [plant](/rp-engine/blocks#plants), on cut tripwire | | `CHORUSBLOCK` / `CHORUS`, the old `chorusblock` | `shape: grate`, the see-through full block | | a mushroom type | `base: mushroom_stem` | | Oraxen's `STAIR`, `SLAB`, `DOOR`, `TRAPDOOR`, `GRATE`, `BULB` | that [`shape:`](/rp-engine/blocks#stairs-slabs-doors-and-other-shapes), made from the block's textures (a door's `[bottom, top]`, a bulb's `[off, on]`), on **the same waxed copper Oraxen used**: `custom_variation` 1 to 4 is fresh, exposed, weathered, oxidized | What a block does comes across where there is an equivalent: | Nexo / Oraxen | RP Engine | |---|---| | `directional` `LOG` · `FURNACE` · `DROPPER` / `BARREL` | `rotate: axis` · `horizontal` · `all`. Where the set names a block per direction (`y_block`, `north_block`, ...), each direction wears that block's model, and those blocks are not placed as blocks of their own | | `storage` | `storage`, the same kinds | | `is_falling` | `falls` | | `blast_resistant` | `blast-resistant` | | `log_strip` (`stripped_log`, `drop`) | `strip` | | `light` | `light` | ## Click commands and other behaviour A click action's `[console]`, `[player]`, `[message]`, `[actionbar]` and `[sound]` (with its volume and pitch) become `console`, `run`, `message`, `actionbar` and `sound` steps, and `` and `%p%` become `{player}`. Oraxen's newer `events` read the same way, `executor: console` or `player`. A condition that only checks a permission (`#player.hasPermission("x")`) becomes a `permission` step; any other condition is a branch, which actions do not have, so what sits behind it is skipped and named. A `commands` cooldown comes across in Nexo's units (`5s`, `10t`) or Oraxen's milliseconds. ## What does not Each of these is a warning naming the ID when the pack loads, so nothing is dropped silently. Most of a world does not come across Block and furniture *definitions* translate. Most of what is already placed in a world does not: the vanilla state a note-block or string block hides in was allocated by the plugin against its own numbering, and placed furniture is the plugin's own entities. Those have to be rebuilt or remapped by hand. **Oraxen's shapes are the exception.** Its stairs, slabs, doors, trapdoors, grates and bulbs keep the very waxed copper Oraxen put them on, so the ones already standing in a world are still those blocks after the move. The note-block pool here is also [smaller](/rp-engine/blocks), 49 per base, because the instrument cannot be part of a block's identity. A pack with hundreds of blocks will not fit as it stands. **Furniture behaviour with nothing to land on**: beds (the game only lets a player sleep in a bed block, and wakes anybody lying anywhere else), a `connectable` that picks its look from one item model reading the connection off the item (name the five looks and it joins), text floating over a piece, a `modelengine_id` (import the `.bbmodel` and give the item that model instead), a farmland requirement, BlockLocker protection, a left-click event on a placed piece (a left click breaks it here), `opped_player` commands, `armor_effects`, backpacks and the rest of `Mechanics`. Each is named with the reason. The item still loads. **One list of states per piece.** A door, Nexo's states, a switched light and `rotatable` all become the piece's states, and a piece has one list of them, so where a piece has several the first in that order wins and the others say so. Of a door, its `open_properties` rotation is not carried (an open hinged door turns a quarter here) and nor is `delay_hitbox_toggle`. Of Nexo's states, Model Engine and CustomModelData states, `conditions` and `next_after` are not carried. Of `evolution`, `light_boost`, `rain_boost` and bone meal are dropped: a piece here grows at one steady chance. **Block behaviour with nothing to land on**: of a string block, `sapling` (growing into a pasted schematic; [`grow:`](/rp-engine/blocks#growing) steps a plant through its own stages instead), `is_tall` (only the lower block is the plant), `random_place`, `stackable`, `requires_supporting` and `placeable_on_water`; `directional` on anything but a full block; and `beacon_base_block`, `farmblock`, `limited_placing` and `placeable`, each with its reason. **More than one of something**: extra seats, extra lights and extra hitboxes. The first (or the one at the anchor) comes across, and the warning counts the rest. **Some of a glyph**: tab completion, a fixed `char`, a font of its own and `is_emoji`, because an RP Engine icon goes into the default font and is given its character by ID; a GIF's `offset` (use `ascent`); and placeholders on a multi-bitmap glyph, which became several icons a placeholder cannot type all of. **Animated glyphs move where RP Engine's icons move, and are their first frame in chat**: see [why](/rp-engine/icons#where-it-moves-and-where-it-does-not). **Cauldron, grindstone, crafter, transmute and predicate recipes**, and any recipe with an ingredient that is a tag or another plugin's item. Those are skipped whole and named, rather than loaded with an ingredient missing. A recipe's `permission` is not carried across either: RP Engine recipes are open to everyone. **Sounds that replace a vanilla one** (`minecraft:` ids and `replace: true`): put those in `overrides/sounds.json` instead. ## Good to know **Armour art stays where it is.** Both plugins pair a set's art with its pieces by name, `ruby_armor_layer_1.png` for the body and boots and `_2.png` for the leggings of the `ruby` set, and RP Engine does the same: it finds those files wherever they are in the pack and serves them on [vanilla's equipment path](/rp-engine/armour). Component, trim and the old shader armour all use the same art, so all three come across. It is drawn from Minecraft 1.21.4; on an older server the armour is still worn but with vanilla art, and the build names every piece that will. An elytra's wings are not carried, because RP Engine draws worn items on a player's body only. **Some art has to move.** RP Engine reads icons from `assets/textures/font/`, and Nexo and Oraxen keep them elsewhere. The load warns with the exact path. **Seats are worth a look in game.** Oraxen measures a seat from where its armour stand stands and RP Engine from where the rider sits, so Oraxen seats are converted and the load says so. Nexo seats come across as written. Either way, if a chair sits people slightly wrong, adjust its `seat:`. --- Source: https://resourcepack.ai/docs/rp-engine/objects # 3D objects A 3D shader object is something a shader draws in the world rather than a block model: a black hole, a portal, a ball of fire, a bomb that goes off. You make them in Studio (see [Shaders](/shaders)). RP Engine puts them in the world and drives them: which state each one shows, where it is, which way it faces and how big it is. The client animates every change smoothly. ![3D objects: a black hole, a ringed planet, a galaxy in a globe and a fireball](/images/shaders.webp "plain") Requirements: - A server on Minecraft 1.21.4 or newer. - The Studio pack built for Minecraft 26.2 or newer, and players on a version that pack draws objects for. These are different from the HUD shader objects that `/rp shaders` and `/rp shader` show on a player's screen. ## Getting one on a server Make the object in Studio and push the pack to your server (see [Testing on your server](/testing/plugin)). It is then known to the server as `studio:`. Put one down and try its states: ``` /rp objects /rp object spawn studio:portal /rp object state opening ``` `/rp objects` lists every object with its size, states and sequences. ## States States are the object's looks, defined by its code: a portal might have `idle`, `opening` and `open`. Entering a state starts its clock, so a one-shot (an explosion, a portal opening) plays from the start for everyone watching, and the object can blend from the state before. A state left alone for three minutes is shown as finished. A placed object keeps its place, state, turn and size through a restart. A sequence or move that was running does not carry on. ## Commands | Command | What it does | |---|---| | `/rp objects` | Lists the objects, their states and sequences | | `/rp object spawn [size] [x y z] [world]` | Puts one down in front of you, or at those coordinates. `size` is its diameter in blocks | | `/rp object state ` | The nearest object enters a state. With no name, lists its states | | `/rp object replay` | Plays its current state again from the start | | `/rp object play ` | Runs one of its [sequences](#sequences) | | `/rp object stop` | Stops its sequence and any move in progress | | `/rp object move [time] [ease]` | Moves it. `~` is where it is now, `~2` two blocks on | | `/rp object turn [time] [ease]` | Turns it, in degrees. `~` adds to its current angle | | `/rp object size [time] [ease]` | Makes it bigger or smaller | | `/rp object seed <0-15>` | A number the object's code may use to vary its look | | `/rp object remove [all]` | Takes the nearest one away, or every one | Everything except `spawn` acts on the nearest object within 64 blocks (for `state` and `play`, the nearest one that has that state or sequence). `time` is ticks (`40`) or seconds (`2s`), and leaving it out makes the change instant. `ease` is `linear`, `in`, `out` or `in_out` (the default). Every verb works from a command block or through `execute`. From the console only `spawn` works, and it needs a size and coordinates. ## Permissions Each verb has its own node, so you can let players run an object's sequences without letting them put new ones down. All default to op. | Permission | What it allows | |---|---| | `rpengine.objects` | `/rp objects` | | `rpengine.object` | Every `/rp object` verb below | | `rpengine.object.spawn` | `spawn` | | `rpengine.object.state`, `.replay` | `state`, `replay` | | `rpengine.object.play`, `.stop` | `play`, `stop` | | `rpengine.object.move`, `.turn`, `.size`, `.seed` | `move`, `turn`, `size`, `seed` | | `rpengine.object.remove` | `remove` | ## Sequences A sequence is a script of steps an object runs: drop from the sky, grow, explode, disappear. They live in the `objects/` folder of a [content pack](/rp-engine/content), in YAML. A file can define new objects or add sequences to one that already exists, including one pushed from Studio: ```yaml # objects/portals.yml extras: for: studio:portal # adds sequences to an existing object sequences: open: - state: opening - turn: {yaw: 90, by: true, over: 2s, async: true} - size: {times: 2, over: 2s} - state: open ``` Run it with `/rp object play open`. A full object, defined by hand: ```yaml # objects/bombs.yml nuke: model: rpai:shader3d_0 # the item model that draws it size: 3 # diameter in blocks when placed states: [idle, detonate] # in the order the object's code numbers them sequences: drop: - state: idle - move: {by: [0, 22, 0]} # no "over": at once - wait: 10 # ticks; or 0.5s - move: {by: [0, -22, 0], over: 2.5s, ease: in} - sound: {name: entity.generic.explode, volume: 16, pitch: 0.5} - size: {to: 40, over: 2s} - state: detonate - wait: 45s - remove ``` | Field | What it is | |---|---| | `model` | The item model that draws the object. Needed unless `for` is set | | `size` | Diameter in blocks, 0 to 256. Defaults to 1 | | `states` | The state names, in the order the object's code numbers them. Up to 16 | | `for` | Instead of `model`: the id of an existing object to add `sequences` to | | `sequences` | Named lists of steps | Steps run in order: | Step | What it does | |---|---| | `state: name` | Enters a state (nothing happens if it's already in it) | | `replay: name` | Enters it, or starts it again if it's already in it | | `seed: 0-15` | Sets the seed | | `move: {to \| by, over, ease, async}` | `by: [x, y, z]` from where it is now; `to: [x, y, z]` from where it was when the sequence began | | `turn: {yaw, pitch, roll, by, over, ease, async}` | Degrees. A missing axis stays put; `by: true` adds instead of setting | | `size: {to \| times, over, ease, async}` | A diameter in blocks, or a multiple of the current one | | `wait: time` | Ticks (`40`) or seconds (`2s`) | | `sound: {name, volume, pitch}` | Plays a sound at the object | | `command: "..."` | Run by the console. `{x}`, `{y}`, `{z}`, `{world}` and `{size}` are the object's | | `settle` | Shows the current state as finished | | `remove` | Takes the object away | | `restart` | Back to the first step, for a sequence that repeats | A move, turn or resize holds the sequence until it's done, unless it has `async: true`. Any single timing is capped at ten minutes. Mistakes in a file are reported when the content loads, and the step or object is skipped. ## From a plugin `engine.shaderObjects()` places and drives objects from Java: ```java ShaderObjects objects = engine.shaderObjects(); if (!objects.supported()) return; // 1.21.4 or newer ContentId nuke = ContentId.parse("studio:nuke").orElseThrow(); ShaderObject bomb = objects.spawn(location, nuke).orElseThrow(); bomb.moveBy(new Vector(0, -20, 0), 50, Easing.IN); // ticks bomb.turnTo(90, 0, 0, 40, Easing.IN_OUT); // yaw, pitch, roll bomb.resize(40, 2, Easing.LINEAR); // diameter in blocks bomb.state("detonate"); bomb.play("drop"); // a sequence from objects/ ``` `at(entity)`, `near(location, radius)` and `loaded()` find objects already placed. A handle lasts as long as its entity. Everything here runs on the main thread. See [the Java API](/rp-engine/api) for getting the engine. --- Source: https://resourcepack.ai/docs/rp-engine/paintball # Paintball An **addon** for [RP Engine](/rp-engine): a plugin that installs into the engine and adds one thing, rather than a pack you author yourself. Drop it in beside the engine and it brings its own content with it. ![A paintball match: a paint grenade, the marker and splats on the walls](/images/paintball.webp) This one is paintball. Hold right-click to fire a paint marker, left-click to aim down its sights, throw a paint grenade round a corner and leave a mine in a doorway. One hit splats you and you are back a few seconds later. Play it as team deathmatch, free for all or capture the flag. One command builds a whole field to play on. ## Installing It needs **Spigot or Paper 1.21.11 or newer** (the marker uses item components 1.21.11 added) and **RP Engine 0.2.3 or newer**. On an older engine Paintball says so in the console and turns itself off. Drop it in Put `RPE-paintball.jar` in `plugins/` beside `RPEngine.jar` and start the server. Paintball copies its models, sounds, HUD and scoreboard into `plugins/RPEngine/content/paintball/` (RP Engine's content folder, which the engine builds its resource pack from) and reloads the engine once. That folder is yours to edit: an update replaces only the files you have not changed. Build a field As an op, stand somewhere flat and run `/pb arena generate main confirm`. It builds a field around you and sets the arena up on it. See [Building an arena](#building-an-arena) before you do this anywhere you have built. Play `/pb join`, then `/pb start`. Alone is fine: you play against nobody, which is a good way to try the marker. If you run Multiverse-Core, Paintball loads after it, so an arena in one of its worlds is found. ## Playing ### The lobby `/pb join` (or `/pb` on its own) puts you in the lobby: on the field you generate, a glass box over the middle that looks down on it. Your inventory and where you were are put away and given back when you leave. The hotbar holds: | Item | What it does | |---|---| | **Colour** (the marker) | Right-click for the next colour, and round again to Any. Your paint in a free for all; in a team match, your marker | | **Practise** (the target) | Down onto the field to practise until the match starts. See [Practising](#practising) | | **Play for Red** / **Play for Blue** | Pick a side for the next match. Click the same one again to leave it to chance | | **Scoreboard** | The scoreboard of the last match | | **Leave** | Back to where you were, with your things | `/pb team red|blue|auto` does the same as the team items. Sides are kept within one player of each other, so if too many pick one side, the last to pick is moved and told. Late joiners go onto the smaller team. `/pb colour ` does the same as the marker. In a free for all your colour is your paint (marker, mask, suit and splats). In a team match your paint stays your team's and only the marker changes. `colour-pick: false` in the config turns choosing off. More players than spawns is fine: they share them. ### Practising While the lobby waits for a match, the target in the hotbar (or `/pb practice`) takes you down onto the field to try the marker and learn the map. You get the marker and the grenade, in the colour you chose or your side's, and everybody down there plays against everybody. A hit sends whoever it hit straight back to a spawn, the HUD keeps a practice score, and nothing counts towards anything. The feather in your last slot, or `/pb practice` again, takes you back up to the lobby. When the match starts, everybody practising is put at their spawn like everybody else and the paint comes off the walls. `practice: false` in the config, or for one arena with `/pb arena set`, turns practising off. ### In a match Every match opens with a three-second countdown, frozen in place, then a whistle. You carry a marker, a paint grenade, a paint mine, a mask and a suit in your team's colour. | Key | What it does | |---|---| | **Right-click** (hold) | Fire. About seven balls a second, forty to a hopper | | **Left-click** | Up to the sights, or back down. Zoomed in, slower on your feet, and no spread at all | | **Q** | Reload. The marker also reloads by itself when the hopper runs dry | | **Right-click** the grenade | Throw it | | **Right-click** the ground with the mine | Set it | | **F** | The scoreboard | | **Tab** | The scoreboard in the player list: the score and the clock on top, and a tile for every player with their kills and deaths | **Every ball lands on the crosshair.** Balls drop and slow as they fly, but are aimed so they arrive where you are looking. From the hip they stray a little (the crosshair's ticks show how much): more on the move, in the air or sprinting, half as much crouched. Down the sights there is no spread. Changing slot, sprinting or reloading takes you off the sights. **The grenade** goes off a second and a half after it lands and splats every enemy within three and a half blocks that it can see, so a wall is cover. It recharges for fifteen seconds after a throw (`grenade.reset-on-respawn: true` makes a respawn bring it straight back). **The mine** is one per match. It arms a second and a half after you set it, and the first enemy to step on it splats every enemy within three blocks that it can see. Your own team can walk over it. **One hit splats you.** For three seconds the camera circles whoever got you, then you come back at one of your team's spawns, safe from hits for a second and a half. A server can also give each spawn a safe zone (`spawn-protection-radius`): you stay safe until you leave it or fire, and the other side cannot set a mine in it. There is no friendly fire, and enemy name tags are hidden. A pling sounds at one minute and thirty seconds left, and the last seconds count down in the middle of the screen. The match ends when the clock runs out (three minutes) or when a team reaches the kill limit, if one is set. Then the result, the scoreboard, and back to the lobby. Splats are displays, not blocks, so the arena is never changed and is clean for the next match. ### What you see There is not a title or a boss bar in the game. **The whole screen is one HUD**: - **Top centre**, the score strip: both teams' kills and the clock. - **Top left**, the kill feed: the last three splats, who by, and with what. - **Bottom right**, your weapon: the grenade's card, filling as it recharges, and the ammo panel with its bar. - **The crosshair**, with its spread ticks from the hip and a hit marker when you land one. - **The middle**, which carries every moment of a match: the countdown ring, GO!, the paint on your screen when you are splatted and the ring counting you back in, SPLATTED and who when you get somebody, the time left as the clock runs down, and the result on its band with the final score. **The scoreboard** (F, `/pb scoreboard`, or the lobby's item) is a dialog with both teams' tables, the top five of each, best first: each player's face, kills, deaths and accuracy. **The player list** (Tab) is a scoreboard too. Under the name, the mode, the map, the score and the clock, every player has a tile in their colour with their name and their kills and deaths: a column a team, red on the left, or in a free for all everybody best first with their place. Your own tile is lit, and the name of somebody who is out is greyed. In the lobby it shows who is waiting, in the colour of the side they picked. On Paper the players in the match are taken off the list under the tiles, which already show them; Spigot has no way to, so there they stay. `tab.scoreboard: false` keeps the game's own list instead. ### While you are playing In the lobby and in a match alike, you take no damage and get no hungrier, and you cannot build, break, open doors or chests, pick anything up, or move or drop what you carry. Commands are limited to `/pb`, `/msg`, `/tell`, `/w`, `/r`, `/reply`, `/me` and `/list`, unless you have `paintball.bypass.commands`. Walking out of the arena's bounds during a match puts you back where you last stood. `/pb leave` always works. Disconnecting or being teleported to another world counts as leaving. If the server goes down mid-match, everybody gets their things back the next time they join. ## Game modes Every arena plays one of three modes, `teams` unless it says otherwise. | Mode | How it plays | |---|---| | **Team deathmatch** (`teams`) | Red against blue. Most splats when the clock runs out wins, or the first team to the kill limit if there is one | | **Free for all** (`ffa`) | Everybody against everybody, each in a paint colour of their own. First to 15 splats, or the most when the clock runs out, wins | | **Capture the flag** (`ctf`) | Red against blue, for each other's flag. First team to 3 captures, or the most when the clock runs out, wins | Choose an arena's mode with `/pb arena set mode ffa`, or play another one for a single match with `/pb start ctf`. The lobby says which mode is next. `max-players` caps how many people an arena takes, its lobby and its match together, so one arena can be a four-player free for all and another a 5v5 (`/pb arena set max-players 4`). Anybody past it is told the arena is full. Bots are not counted, and 0 is no limit. ### Free for all Every player gets one of eight paint colours (red, blue, green, orange, yellow, purple, pink and cyan), unless they chose one. More players than colours share them. Everybody else is an enemy, and nobody's name tag shows. You respawn at whichever spawn is furthest from everybody still in. The HUD shows your kills and the leader's either side of the clock, with your place under them. A tie on kills goes to whoever was splatted less; a tie on both is a draw. The scoreboard is one table of everybody. ### Capture the flag Each team has a flag at its base. Walk into the other team's flag to take it. While you carry it you glow, walk a little slower, and cannot aim down the sights, throw your grenade or set your mine. Bring it to your own flag while yours is at home and your team scores a capture. If the carrier is splatted, the flag drops where they fell. An enemy can pick it up again. A teammate of the flag's who touches it sends it home, and otherwise it goes home on its own after twenty seconds. The HUD shows each flag's state beside its team's captures: at home, taken or dropped. The middle of the screen and chat say when a flag is taken, dropped, returned or captured. A generated field has both flags in place. On an arena you set up by hand, stand where each one goes and run `/pb arena setflag red` and `blue`. ## Running matches Matches do not start on their own: somebody with `paintball.start` runs `/pb start`. - **`/pb start`** starts a match now on the arena you are in, joining you first if you are not in (so it works alone). `/pb start ` names one, and `/pb start ` plays that mode this once. - **`/pb stop`** ends a match the ordinary way (result, scoreboard, lobby). In the lobby it sends everybody home. **`/pb as `** runs a subcommand as somebody else, for NPCs and command blocks: an NPC that runs `/pb as join` for whoever clicks it is a join button. It is checked against **the player's** permissions, not the sender's. ### Bots Computer players can fill a match up. They are off until you turn them on in `config.yml`, or for one arena with `/pb arena set`: - **`bots.fill`**: fill each side up to this many in a team match, or everybody up to this many in a free for all. - **`bots.even-teams`**: in a team match, add a bot for every extra person the other side has, so three against one becomes three against three. Bots are in the kill feed, the scoreboard and the score like anybody else. They shoot the nearest enemy they can see after a short reaction time (`bots.reaction-ticks`), with some spread (`bots.spread-degrees`). In capture the flag half of them attack and half guard. They do not throw grenades or set mines, and never count towards stats. A person who joins takes a bot's place, and when the last person leaves the match ends. Bots are mannequins, so they need Minecraft 1.21.9 or newer. ## Building an arena An arena is a waiting spot, at least one spawn for each team, and bounds: the box a player cannot walk out of during a match. Arenas are kept in `plugins/RPEPaintball/arenas.yml`. An arena id is lower-case letters, digits, `-` and `_`, up to 32 of them; its display name can be anything. ### Generate a field ``` /pb arena generate confirm [name] ``` Builds a speedball field centred on you and sets the arena up on it, ready to play: a floor, a netted fence, a base and flag at each end, mirrored bunkers, and a glass box over the middle to wait in. Without `confirm` it only says what it is about to do. It replaces every block in a large box The field is 31 blocks across and 57 long. Inside that it clears everything from your feet to eleven blocks up, lays the floor and a foundation in the two layers below, and builds the waiting box above the middle, up to seventeen blocks above your feet. Run it in an empty world, or somewhere you do not mind losing. A flat world is best. Running it again with the same id rebuilds the field where you now stand. From the console, name the place outright: ``` /pb arena generate at [name] ``` ### Set one up by hand To play on a map you built yourself, stand in the right places and run: Create it `/pb arena create [name]`, in the world the arena is in. Where players wait `/pb arena setwaiting ` where you stand, facing the way you face. Spawns `/pb arena addspawn red`, and again for `blue`, up to five a team (past five the oldest goes). With no colour, `/pb arena addspawn ` adds a spawn for anybody (up to ten), used by free for all and by any team with no spawns of its own, so a free-for-all arena needs no team spawns. `/pb arena clearspawns [red|blue]` clears them. Bounds `/pb arena wand` hands you the bounds wand. Left-click a block for one corner, right-click another for the opposite corner, then `/pb arena setbounds `. Open it `/pb arena enable `. If anything is missing it says what. `/pb arena list` shows every arena, its world, and whether it is open, ready, or what it still needs. ### Managing arenas `/pb join` with no arena named goes to the first open one. `/pb arena disable ` closes an arena for maintenance: nobody can join or start it, its lobby is sent home, and a match on it ends as `/pb stop` would. Staff can still `tp` there and change it. `/pb arena delete ` does the same and forgets the arena, leaving the blocks where they are. Spawns and bounds cannot be changed during a match: `/pb stop ` first. ### Settings per arena Every number in [the configuration](#configuration), and each team's marker, is the server's default. An arena can set any of them for itself: ``` /pb arena set