Skip to content

Commit c47d0a1

Browse files
SnaveSutitSnaveSutit
committed
📝 Add docs for Texture Slots, Variant config, tints, and upgrading
- New 1.11.0 features had no docs - Upgrading page covers the breaking changes for existing projects
1 parent 89ca35f commit c47d0a1

6 files changed

Lines changed: 267 additions & 0 deletions

File tree

‎src/docs/configs/item-model-properties/en.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Item Model Properties
3+
description: Tint a bone's faces in-game with vanilla tint sources.
4+
---
5+
6+
# Item Model Properties
7+
8+
Item Model Properties control how a bone's faces are **tinted** in-game. A tint multiplies a face's texture by a color, which lets you recolor parts of a rig without making new textures. For example, you could tint a shirt with the color of the player's team, or a potion bottle with its potion's color.
9+
10+
Open it by right-clicking a [Group](/docs/nodes/groups) that contains Cubes and choosing **Item Model Properties**. Requires **Minecraft 1.21.4 or newer**.
11+
12+
## How Tints Work
13+
14+
1. In Blockbench, set the **Tint** of the faces you want to recolor to a tint index (`0`, `1`, `2`, …) in the face properties of the UV panel.
15+
2. In Item Model Properties, add one tint per index. The first tint in the list is index `0`, the second is index `1`, and so on.
16+
17+
Faces without a tint index are never tinted.
18+
19+
If a bone has no tints configured, Animated Java gives it a white **Dye** tint at index `0`. Faces with tint index `0` can then be recolored in-game by setting the bone item's `minecraft:dyed_color` component.
20+
21+
## Tint Types
22+
23+
Each tint has a **Type**. Click a tint to show its settings.
24+
25+
| Type | Color comes from |
26+
| --------------------- | -------------------------------------------------------------------------------- |
27+
| **Constant** | Always the same color. |
28+
| **Dye** | The item's `dyed_color` component. |
29+
| **Firework** | The colors of the item's firework explosion component. |
30+
| **Potion** | The color of the item's potion contents. |
31+
| **Map Color** | The item's map color component. Not available in Minecraft 26.3 and newer. |
32+
| **Team** | The team color of the entity displaying the item. |
33+
| **Grass** | The grass colormap, at a set **Temperature** and **Downfall** (each `0` to `1`). |
34+
| **Custom Model Data** | An entry in the item's `custom_model_data` colors list, picked by **Index**. |
35+
36+
Every type except Constant and Grass also has a **Default Color**, used when the item doesn't have the component (or, for Team, when the entity isn't on a team with a color).
37+
38+
:::note[Transparency]
39+
Alpha only works on **Dye** and **Firework** tints, and only because of a vanilla bug ([MC-278626](https://bugs.mojang.com/browse/MC-278626)). It may stop working in a future Minecraft version. With cutout textures, faces below about 10% alpha disappear, and the rest render fully opaque.
40+
:::
41+
42+
If your Target Minecraft Version doesn't support a tint's type, the dialog warns you, and exporting fails until you change or remove it.
43+
44+
## Related Reading
45+
46+
- [Groups](/docs/nodes/groups)
47+
- [Cubes](/docs/nodes/cubes#supported-features)

‎src/docs/configs/variant/en.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: Variant Config
3+
description: Configure a Variant's name, Texture Slots, excluded nodes, and On-Apply function.
4+
---
5+
6+
# Variant Config
7+
8+
The Variant Config dialog sets up one [Variant](/docs/core-concepts/variants). Open it by clicking the edit (pencil) icon next to a Variant in the **Variants** panel.
9+
10+
## Fields
11+
12+
### Display Name
13+
14+
The Variant's name in the editor and in error messages. Can contain any characters.
15+
16+
### Name
17+
18+
The Variant's exported name, used in its function path:
19+
20+
```mcfunction
21+
<blueprint_id>/variants/<name>/apply
22+
```
23+
24+
Only lowercase letters, digits, and underscores are allowed, and every Variant needs a unique Name.
25+
26+
### Generate Name From Display Name
27+
28+
When enabled (the default), the Name is generated from the Display Name automatically. Turn it off to type your own.
29+
30+
:::warning
31+
Changing the Name changes the Variant's function path. Update any commands that call it.
32+
:::
33+
34+
### Texture Slots
35+
36+
The texture each [Texture Slot](/docs/core-concepts/texture-slots) switches to when this Variant is applied. Slots that aren't listed are left as they are.
37+
38+
Not available on the Default Variant, which always resets every slot to its default texture.
39+
40+
### Excluded Nodes
41+
42+
Nodes this Variant never changes, even if they have faces in one of its Texture Slots or their own [per-Variant settings](/docs/configs/display-entity#per-variant). Drag nodes between the **Included Nodes** and **Excluded Nodes** columns.
43+
44+
Not available on the Default Variant.
45+
46+
### On-Apply Function
47+
48+
Commands that run `as` and `at` the root entity whenever the Variant is applied. Supports [MC-Build](https://mcbuild.dev) syntax.
49+
50+
## Related Reading
51+
52+
- [Variants](/docs/core-concepts/variants)
53+
- [Function API: Variants](/docs/function-api/variants)
54+
- [Display Entity Config](/docs/configs/display-entity)

‎src/docs/core-concepts/texture-slots/en.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Texture Slots
3+
description: Swap the textures on parts of your rig at runtime with Texture Slots.
4+
---
5+
6+
# Texture Slots
7+
8+
## What is a Texture Slot?
9+
10+
A **Texture Slot** is a group of interchangeable textures. You paint faces with the slot instead of a single texture, and every one of those faces can then switch to any texture in the slot, in the editor and in-game.
11+
12+
Slots are perfect for anything with a few alternative looks: eyes that blink, a screen with several images, a shirt in different colors.
13+
14+
The first texture in a slot is its **default**. Faces show it until something switches the slot.
15+
16+
## Creating a Slot
17+
18+
1. In the **Textures** panel, select the textures you want in the slot. Hold `Ctrl` or `Shift` to select several.
19+
2. Click **Create Texture Slot** in the Textures panel's toolbar.
20+
3. Name the slot in the dialog that opens.
21+
22+
The slot appears in the Textures panel like any other texture, with its own icon.
23+
24+
### The Texture Slot Dialog
25+
26+
Double-click a slot (or right-click it and choose **Texture Slot Properties**) to edit it:
27+
28+
- **Name**: used to name the slot's functions and models when exporting.
29+
- **Textures**: every texture in the slot. Drag them to reorder; the first one is the default. Use **Add Texture** to add more, and the eye icon to show a texture in the editor.
30+
31+
## Using a Slot
32+
33+
Apply a slot to faces the same way you'd apply a texture: select the faces or Cubes, then right-click the slot and choose **Apply to Faces** or **Apply to Elements**.
34+
35+
- To preview another texture in the editor, right-click the slot and pick one under **Preview**. Previews aren't saved.
36+
- Painting on a slot paints whichever texture it's currently showing.
37+
- Deleting a slot moves its faces back to the slot's default texture.
38+
39+
## Switching Slots In-Game
40+
41+
There are three ways to change what a slot shows:
42+
43+
- **Functions:** each slot gets a function per texture, like `my_pack:my_rig/texture_slots/eyes/closed`. See [Function API: Texture Slots](/docs/function-api/texture-slots).
44+
- **[Variants](/docs/core-concepts/variants):** a Variant picks a texture for any of your slots, and applies them all at once.
45+
- **Texture Slot keyframes:** switch slots at a specific frame of an [animation](/docs/core-concepts/animations#effect-keyframes).
46+
47+
Each slot switches independently. Changing `eyes` never affects `shirt`, even on the same bone.
48+
49+
### Names
50+
51+
Slot and texture names are turned into function names when exporting: they're lowercased, a trailing `.png` is removed, and anything other than letters, digits, and underscores becomes `_`. A texture named `Eyes Closed.png` becomes `eyes_closed`. If two names end up the same, Animated Java adds a number to keep them unique.
52+
53+
## Version Support
54+
55+
Switching a single slot needs **Minecraft 1.21.4 or newer**. On older versions, the slot functions and Texture Slot keyframes aren't available, and slots only change when a Variant is applied (see [Layering Variants](/docs/core-concepts/variants#layering-variants)).
56+
57+
:::info[How it works]
58+
On 1.21.4 and newer, each bone's item stores the texture name of every slot it uses in its `minecraft:custom_model_data` strings, and its item model picks textures from those strings. Switching a slot just rewrites one string, so no extra models are needed.
59+
:::
60+
61+
## Upgrading Older Blueprints
62+
63+
Before 1.11, Variants swapped textures with a texture map. Opening an older Blueprint turns each swapped texture into a Texture Slot holding it and every texture it was swapped to, and updates its Variants to use those slots. Your Variants look the same as before.
64+
65+
## Related Reading
66+
67+
- [Variants](/docs/core-concepts/variants)
68+
- [Function API: Texture Slots](/docs/function-api/texture-slots)
69+
- [Animations](/docs/core-concepts/animations)

‎src/docs/function-api/texture-slots/en.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: Texture Slots
3+
description: How to switch Texture Slots on a Rig instance.
4+
---
5+
6+
# Texture Slots
7+
8+
Every [Texture Slot](/docs/core-concepts/texture-slots) gets one function per texture in it:
9+
10+
```
11+
<blueprint_id>/texture_slots/<slot>/<texture>
12+
```
13+
14+
Running one switches every face in that slot, on every bone of the rig, to that texture. Other slots aren't affected.
15+
16+
These functions must be run **as the root entity** of the rig, and require **Minecraft 1.21.4 or newer**.
17+
18+
```mcfunction
19+
# Close the eyes of every my_rig instance
20+
execute as @e[tag=my_pack.my_rig.root] run function my_pack:my_rig/texture_slots/eyes/closed
21+
```
22+
23+
`<slot>` and `<texture>` are the exported names of the slot and texture. See [Names](/docs/core-concepts/texture-slots#names) for how they're made.
24+
25+
They return success `1`, so you can use them in `execute if function`:
26+
27+
```mcfunction
28+
execute as @e[tag=my_pack.my_rig.root] if function my_pack:my_rig/texture_slots/eyes/closed run say Blink!
29+
```
30+
31+
## Other Ways to Switch Slots
32+
33+
- Apply a [Variant](/docs/function-api/variants) that sets the slot.
34+
- Add a Texture Slot keyframe to an [animation](/docs/core-concepts/animations#effect-keyframes).
35+
36+
## Related Reading
37+
38+
- [Texture Slots](/docs/core-concepts/texture-slots)
39+
- [Function API: Variants](/docs/function-api/variants)

‎src/docs/resources/upgrading-to-1-11/en.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Upgrading to 1.11
3+
description: What changed in Animated Java 1.11, and how to update your projects.
4+
---
5+
6+
# Upgrading to 1.11
7+
8+
Animated Java 1.11 adds [Texture Slots](/docs/core-concepts/texture-slots), reworks how [Variants](/docs/core-concepts/variants) work, and supports Minecraft 26.3. Most projects upgrade automatically, but a few changes can break Data Pack code or plugins that depend on Animated Java's output.
9+
10+
## Upgrading a Blueprint
11+
12+
1. Open the Blueprint in Animated Java 1.11. It's upgraded automatically. Variants that used to swap textures now use Texture Slots instead, and look the same as before.
13+
2. Save it.
14+
3. Re-export it.
15+
4. In Minecraft, `/reload`, then remove and re-summon every existing instance of the rig. With a debug export, old instances glow red to show they're outdated.
16+
17+
## Breaking Changes
18+
19+
### Animation frame objectives
20+
21+
Each animation's frame score now includes the Blueprint ID, so two Blueprints with the same animation names no longer share a score:
22+
23+
```
24+
Before: aj.<animation>.frame
25+
After: <blueprint_id>.<animation>.frame
26+
```
27+
28+
In the objective name, the `:` and `/` in your Blueprint ID become `.`, so `my_pack:my_rig` gives `my_pack.my_rig.walk.frame`. Update any commands that read or set these scores.
29+
30+
### Bone `custom_model_data` on 1.21.4 and newer
31+
32+
Each bone item's `minecraft:custom_model_data` strings now hold the current texture of each Texture Slot the bone uses, instead of the name of the applied Variant. If your own resource pack or commands read these strings, update them.
33+
34+
### Plugin JSON format version 3
35+
36+
[Plugin exports](/docs/core-concepts/exporting#plugin-exports) now use `format_version` 3:
37+
38+
- `display_properties` is renamed to `entity_properties`.
39+
- `settings.id` no longer starts with `animated_java:`.
40+
- `texture_palettes` is replaced by `texture_slots`.
41+
- Texture keys no longer end in `_png`.
42+
- Variants are exported in a new `variants` section, and applied with `variant` keyframes, instead of being flattened into `texture_slot` keyframes.
43+
44+
Plugins that read Animated Java's JSON need to update to the new format.
45+
46+
## Other Changes Worth Knowing
47+
48+
- The default Target Minecraft Version is now 26.2.
49+
- **Auto Update Rig Orientation** moved to the [Rig page](/docs/core-concepts/blueprints#rig) of Blueprint Settings.
50+
- Entity display names were removed from rig entities, which improves performance.
51+
- Plugin exports no longer build a Resource Pack, and now include Interactions and each node's parent.
52+
53+
The full list is in the changelog: **Animated Java <i class="minecraft-right-arrow"></i> Changelog** in Blockbench.

‎src/lib/docs/navigation.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ export const docsSidebar: DocSection[] = [
3737
{ title: 'Rigs', to: '/docs/core-concepts/rigs' },
3838
{ title: 'Animations', to: '/docs/core-concepts/animations' },
3939
{ title: 'Variants', to: '/docs/core-concepts/variants' },
40+
{ title: 'Texture Slots', to: '/docs/core-concepts/texture-slots' },
4041
{ title: 'Tags', to: '/docs/core-concepts/tags' },
4142
],
4243
},
@@ -60,6 +61,7 @@ export const docsSidebar: DocSection[] = [
6061
{ title: 'Remove', to: '/docs/function-api/remove' },
6162
{ title: 'Animations', to: '/docs/function-api/animations' },
6263
{ title: 'Variants', to: '/docs/function-api/variants' },
64+
{ title: 'Texture Slots', to: '/docs/function-api/texture-slots' },
6365
{ title: 'Utilities', to: '/docs/function-api/utilities' },
6466
],
6567
},
@@ -68,6 +70,8 @@ export const docsSidebar: DocSection[] = [
6870
items: [
6971
{ title: 'Animation', to: '/docs/configs/animation' },
7072
{ title: 'Display Entity', to: '/docs/configs/display-entity' },
73+
{ title: 'Variant', to: '/docs/configs/variant' },
74+
{ title: 'Item Model Properties', to: '/docs/configs/item-model-properties' },
7175
],
7276
},
7377
{
@@ -78,6 +82,7 @@ export const docsSidebar: DocSection[] = [
7882
title: 'Resources',
7983
items: [
8084
{ title: 'FAQ', to: '/docs/resources/faq' },
85+
{ title: 'Upgrading to 1.11', to: '/docs/resources/upgrading-to-1-11' },
8186
{ title: 'Legacy Releases', to: '/docs/resources/legacy-releases' },
8287
],
8388
},

0 commit comments

Comments
 (0)