Texture Atlases #221
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| # Texture Atlases | ||
|
|
||
| Many textures in Minecraft are compiled within Atlases (also known as sprite sheets) for optimisation purposes. Most of them are automaticaly generated by Minecraft when registered throught the use of datapacks or [Registries][reg] (such as block textures). | ||
|
|
||
| ## Texture Atlas Sources | ||
|
|
||
| Texture atlas sources are json files located inside the `atlases` asset folder. | ||
| A texture atlas source describes the name of the targeted atlas and its contents. Additions to the atlases need to be created under the namespace of a mod or datapack. | ||
|
There was a problem hiding this comment. Additions to what atlas? Are you talking about creating your own atlas here, or adding to an existing atlas? |
||
|
|
||
| As of today 14 different atlas sources can be declared: | ||
|
There was a problem hiding this comment. When is today? State it as fact rather than specifying a time. It can always be updated later. Also, the sources are not to be declared. Those are the existing sources that vanilla adds. Is it necessary to be aware of the files themselves though? I think it's better to specify how to use them in the codebase instead. |
||
|
|
||
| |File name|Description| | ||
| |--|--| | ||
| |`blocks`|Block textures| | ||
| |`banner_patterns`|Banner patterns| | ||
| |`beds`|Every bed variant (i.e. colors)| | ||
| |`chest`|Chest textures| | ||
| |`shield_patterns`|Shield textures and patterns| | ||
| |`shulker_boxes`|Every shulker related textures (Shulker box variants, head and projectile)| | ||
| |`signs`|Sign textures| | ||
| |`particles`|Particle textures| | ||
| |`paintings`|Every painting| | ||
| |`mob_effects`|Potion effect icons| | ||
| |`gui`|Every GUI wigets (buttons, scroll bars...)| | ||
| |`map_decorations`|Icons displayed on a map (banners, locations...)| | ||
| |`armor_trims`|Armor trim patterns for every material| | ||
| |`decorated_pot`|Texture for the decorated pot and every sherd| | ||
|
|
||
| ### Creating an atlas source | ||
|
|
||
| To add new textures to an atlas, a new file needs to be created in the `atlases` asset folder: `resources/assets/example_mod/atlases`. | ||
|
There was a problem hiding this comment. Any file? How does the codebase knows what to reference for the atlas itself? |
||
|
|
||
| The file named the same as the altas it is appending to, will then describe what file will be added to the atlas: | ||
| ```json | ||
|
There was a problem hiding this comment. Use json5 format. See https://docs.neoforged.net/contributing#code-references for more information. |
||
| -- Inside gui.json | ||
| { | ||
| "sources": [ | ||
| -- Gather all sprites within the "source" folder | ||
| { | ||
| "type": "minecraft:directory", | ||
| "prefix": "", | ||
| "source": "gui/sprites/widgets" | ||
|
There was a problem hiding this comment. What does this mean? What is prefix doing? Is the folder the default namespace or any asset pack? |
||
| }, | ||
| -- Gather sprites within the "icons" spritesheet | ||
| { | ||
| "type": "minecraft:unstitch", | ||
| "resource": "example_mod:gui/sprites/icons", | ||
| "divisor_x": 0.0, | ||
| "divisor_y": 0.0, | ||
| "regions": [ | ||
| { | ||
| "sprite": "example_mod:energy_low", | ||
| "x": 0.0, | ||
| "y": 0.0, | ||
| "width": 8.0, | ||
| "height": 8.0 | ||
| } | ||
| ] | ||
| } | ||
|
There was a problem hiding this comment. Same thing here. What is this doing? All I understand reading this is that it attempts to merge the texture generated for the icon atlas with your custom one. x, y and the like are not explained. |
||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| All paths are realtive to the texture folder and extentions (`.png`, `.png.mcmeta`) are implied. | ||
|
There was a problem hiding this comment. Are you trying to say that all textures are PNGs? I don't think that's important to state here as the format is already defined in the textures section. Also, we don't know what is referring to a texture here or not as you don't state as such. |
||
|
|
||
|
|
||
| ## Datagen | ||
|
|
||
| Like many resources in Minecraft, texture atlas sources can be proceduraly generated using [datagen][dtgn]. To do so, we extend `SpriteSourceProvider` and override the `gather()` method: | ||
|
|
||
| ```Java | ||
| public class MySpriteSourceProvider extends SpriteSourceProvider { | ||
|
|
||
| // Parameters obtained via GatherDataEvent | ||
| public MySpriteSourceProvider ( | ||
| PackOutput output, | ||
| CompletableFuture<HolderLookup.Provider> lookupProvider | ||
| ) { | ||
| super(output, lookupProvider, "example_mod"); | ||
| } | ||
|
|
||
| @Override | ||
| protected void gather () | ||
|
There was a problem hiding this comment. This should match what's in the example JSON. |
||
| { | ||
| // Creates a new "gui" atlas for the mod's namespace | ||
| SourceList gui = atlas( | ||
| ResourceLocation.fromNamespaceAndPath("example_mod", "gui") | ||
| ); | ||
|
|
||
| // Adds the "resources/assets/example_mod/textures/gui/sprites" folder | ||
| // as a source for the atlas | ||
| sources.addSource(new DirectoryLister("gui/sprites", "")); | ||
|
There was a problem hiding this comment. Where is sources from? A parameter on the source list? |
||
| } | ||
| } | ||
| ``` | ||
|
There was a problem hiding this comment. See other examples on how we show data generation. Usually, we make it a tab-like system and show how to register it via gather data. |
||
|
|
||
| [reg]:../../../concepts/registries.md | ||
| [dtgn]:../../index.md#data-generation | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Additions to what atlas? Are you talking about creating your own atlas here, or adding to an existing atlas?