Texture Atlases #221

Exanc · 2025-01-17T22:14:24Z

Add documentation on texture atlases under Resources > Client > Textures

Adds a general description of texture atlases in general
Adds a section on texture atlas sources
- JSON example
- Datagen example
Adds links in relevant sections

ChampionAsh5357

Thanks for the contribution!

In it's current state, there is a lot of missing detail (e.g., how does a texture atlas work, what is generated, how to access and use it within the game, and what are the available sources to pull from). Also, there are a few spelling mistakes and sentences that need clarification.

ChampionAsh5357 · 2025-01-18T00:41:34Z

docs/resources/client/textures/atlases.md

+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.


Additions to what atlas? Are you talking about creating your own atlas here, or adding to an existing atlas?

ChampionAsh5357 · 2025-01-18T00:41:34Z

docs/resources/client/textures/atlases.md

+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.


Additions to what atlas? Are you talking about creating your own atlas here, or adding to an existing atlas?

ChampionAsh5357 · 2025-01-18T00:43:05Z

docs/resources/client/textures/atlases.md

+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.
+
+As of today 14 different atlas sources can be declared:


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.

ChampionAsh5357 · 2025-01-18T00:43:37Z

docs/resources/client/textures/atlases.md

+
+### 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`.


Any file? How does the codebase knows what to reference for the atlas itself?

ChampionAsh5357 · 2025-01-18T00:44:10Z

docs/resources/client/textures/atlases.md

+To add new textures to an atlas, a new file needs to be created in the `atlases` asset folder: `resources/assets/example_mod/atlases`.
+
+The file named the same as the altas it is appending to, will then describe what file will be added to the atlas:
+```json


Use json5 format. See https://docs.neoforged.net/contributing#code-references for more information.

ChampionAsh5357 · 2025-01-18T00:47:08Z

docs/resources/client/textures/atlases.md

+    {
+      "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
+        }
+      ]
+    }


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.

ChampionAsh5357 · 2025-01-18T00:48:35Z

docs/resources/client/textures/atlases.md

+}
+```
+
+All paths are realtive to the texture folder and extentions (`.png`, `.png.mcmeta`) are implied.


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.

ChampionAsh5357 · 2025-01-18T00:49:28Z

docs/resources/client/textures/atlases.md

+
+```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 ()
+  {
+    // 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", ""));
+  }
+}
+```


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.

ChampionAsh5357 · 2025-01-18T00:50:03Z

docs/resources/client/textures/atlases.md

+
+    // Adds the "resources/assets/example_mod/textures/gui/sprites" folder
+    // as a source for the atlas
+    sources.addSource(new DirectoryLister("gui/sprites", ""));


Where is sources from? A parameter on the source list?

ChampionAsh5357 · 2025-01-18T00:50:28Z

docs/resources/client/textures/atlases.md

+  }
+
+  @Override
+  protected void gather ()


This should match what's in the example JSON.

Exanc · 2025-01-19T14:07:29Z

@ChampionAsh5357 I have rewritten most of the article, please tell me what you think of it when you have the time.

ChampionAsh5357

A few things of note. Currently, you are simply explaining the existing vanilla types and not how to use the texture atlas. Additionally, you should assume that the average reader has little to no knowledge in the system, so they're not going to understand why to use X or Y in a given situation.

A lot of this information seems like it came from the Minecraft wiki page on the atlas JSON format due to similar wording. While that's partially fine, you need to supplement with additional information as to what would be useful to know from a modder's perspective.

Other than that, just spelling and grammar mistakes that I have not added a review for as it should be caught in further rewrites.

ChampionAsh5357 · 2025-01-19T15:59:12Z

docs/resources/client/textures/atlases.md

+
+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).
+
+Optionaly, datapacks can register their own [texture atlas sources][txtatlassource], giving more control over wich sprite or image gets included within an atlas.


It's not giving more control. The sprite sources quite literally determine what is within the final stitched texture.

ChampionAsh5357 · 2025-01-19T15:59:43Z

docs/resources/client/textures/atlases.md

+|Altas 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|


Once again, how are the atlases stored in code? How do I use them?

ChampionAsh5357 · 2025-01-19T16:00:22Z

docs/resources/client/textures/atlases.md

+
+Texture atlas sources are JSON configuration files in ressource packs, that control wich textures of a resource pack are included in the atlases.
+
+Texture atlas sources are located within the `altases` asset folder, under the namespace of the datapack it is gathering textures from. For a datapack named `example_mod` the directory will be located in `resources/assets/example_mod/atlases`.


resources doesn't exist within the compiled jar.

ChampionAsh5357 · 2025-01-19T16:03:51Z

docs/resources/client/textures/atlases.md

+
+### Creating a texture atlas source
+
+To add textures of a datapack to an atlas, a JSON file with the name of the atlas needs to be declared within the `atlases` asset folder.


Does this refer to creating a new sprite source list, or adding to an existing sprite source list. I can tell in the codebase it works similar to tags, but it should be explicitly stated.

ChampionAsh5357 · 2025-01-19T16:04:31Z

docs/resources/client/textures/atlases.md

+    // This texture altas source does not
+    // declare any sprite sources.


Then what's the point of this example? Just say 'Add sources here'.

ChampionAsh5357 · 2025-01-19T16:50:35Z

docs/resources/client/textures/atlases.md

+|`divisor_x`|Used for determining the scale of coordinates on the x axis|
+|`divisor_y`|Used for determining the scale of coordinates on the y axis|


Generally, the divisors should be larger than the texture in question as these are inversely scaling the coordinates.

ChampionAsh5357 · 2025-01-19T16:51:27Z

docs/resources/client/textures/atlases.md

+|`x`     |x coordinate within the file (before scaling by `divisor_x`)|
+|`y`     |y coordinate within the file (before scaling by `divisor_y`)|
+|`width` |width of the sprite (before scaling by `divisor_x`)|
+|`height`|height of the sprite (before scaling by `divisor_y`)|


Scaling will affect the rectangle that is being copied.

ChampionAsh5357 · 2025-01-19T16:52:45Z

docs/resources/client/textures/atlases.md

+## 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:


Mention that SpriteSourceProvider is added by neoforge.

ChampionAsh5357 · 2025-01-19T16:53:47Z

docs/resources/client/textures/atlases.md

+    // Creates a new texture atlas source for the "blocks" atlas
+    SourceList blocks = atlas(
+      ResourceLocation.fromNamespaceAndPath("example_mod", "blocks")
+    );
+
+    /* Adds the "resources/assets/example_mod/textures/blocks"
+       directory as a source for the atlas.
+
+       Adding "block/" at the start of every ResourceLocation's path.
+
+       This will result in "example_mod:block/<my_block>".
+    */
+    gui.addSource(new DirectoryLister("blocks", "block/"));


This is still wrong. gui doesn't exist, and blocks is never used.

ChampionAsh5357 · 2025-01-19T16:57:13Z

docs/resources/client/textures/atlases.md

+    // Registers the new `SpriteSourceProvider`
+    // The fisrt parameter is `true` because Texture Atlases are client
+    // resources and we know that this event is only fired for client resources
+    generator.addProvider(true, new MySpriteSourceProvider(packOutput, lookupProvider));


I would assume we recommend using createProvider now instead of using this.

Exanc added 6 commits January 17, 2025 21:31

Moved rouserces/client/textures.md into it's own subcategory

900b87f

Added the atlases article page

812630f

Added relevant links to the texture atlas article

f2b046e

Little tweak on texture atlases

4fe9d9b

Fixes some mistakes regarding the texture atlas article

86800d1

Add link to SpriteSourceProvider

5b2ac96

Exanc changed the title ~~Text Atlases~~ Texture Atlases Jan 17, 2025

ChampionAsh5357 requested changes Jan 18, 2025

View reviewed changes

Exanc marked this pull request as draft January 18, 2025 14:13

Exanc added 3 commits January 18, 2025 15:14

Added clearer explanations + More details on sprite sources

f2ff876

redo datageneration segment

46528b2

better datagen example

7cdd90e

ChampionAsh5357 requested changes Jan 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Texture Atlases #221

Texture Atlases #221

Exanc commented Jan 17, 2025 •

edited

Loading

ChampionAsh5357 left a comment

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

ChampionAsh5357 Jan 18, 2025

Exanc commented Jan 19, 2025

ChampionAsh5357 left a comment

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

ChampionAsh5357 Jan 19, 2025

		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.


		### 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`.


		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).

		Optionaly, datapacks can register their own [texture atlas sources][txtatlassource], giving more control over wich sprite or image gets included within an atlas.


		Texture atlas sources are JSON configuration files in ressource packs, that control wich textures of a resource pack are included in the atlases.

		Texture atlas sources are located within the `altases` asset folder, under the namespace of the datapack it is gathering textures from. For a datapack named `example_mod` the directory will be located in `resources/assets/example_mod/atlases`.


		### Creating a texture atlas source

		To add textures of a datapack to an atlas, a JSON file with the name of the atlas needs to be declared within the `atlases` asset folder.

		// This texture altas source does not
		// declare any sprite sources.

		\|`divisor_x`\|Used for determining the scale of coordinates on the x axis\|
		\|`divisor_y`\|Used for determining the scale of coordinates on the y axis\|

Texture Atlases #221

Are you sure you want to change the base?

Texture Atlases #221

Conversation

Exanc commented Jan 17, 2025 • edited Loading

ChampionAsh5357 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Exanc commented Jan 19, 2025

ChampionAsh5357 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Exanc commented Jan 17, 2025 •

edited

Loading