mirrors/Unciv
1
0
Fork 0
mirror of https://github.com/yairm210/Unciv.git synced 2025-01-07 14:02:48 +07:00
Code Issues Packages Projects Releases Wiki Activity

Wiki: Texture packing updated (#10851)

Browse Source 
* Wiki: Remove texture atlas info from the Introduction, minor formatting changes

* Wiki: Add texture atlas info back in under Images-and-Audio, expanded (external tools, settings, encoding warning).

* On second thought...

* Double-check wording for 'game.png is no longer a special boy', ensure game atlas is merged into textureRegions only once
This commit is contained in:
SomeTroglodyte 2024-01-04 08:03:48 +01:00 committed by GitHub
parent 42188f160c
commit a37807f4bb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 61 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
core/src/com/unciv/ui/images/ImageGetter.kt
View File

@ -67,7 +67,7 @@ object ImageGetter {
ImageGetter.ruleset = ruleset
textureRegionDrawables.clear()
// Load base (except game.atlas which is already loaded)
// Load base
loadModAtlases("", Gdx.files.internal(""))
// These are from the mods
@ -88,8 +88,8 @@ object ImageGetter {
// See #4993 - you can't .list() on a jar file, so the ImagePacker leaves us the list of actual atlases.
val controlFile = folder.child("Atlases.json")
val fileNames = (if (controlFile.exists()) json().fromJson(Array<String>::class.java, controlFile)
else emptyArray()).toMutableList()
if (mod.isNotEmpty()) fileNames += "game"
else emptyArray()).toMutableSet()
if (mod.isNotEmpty()) fileNames += "game" // Backwards compatibility - when packed by 4.9.15+ this is already in the control file
for (fileName in fileNames) {
val file = folder.child("$fileName.atlas")
if (!file.exists()) continue

49
docs/Modders/Images-and-Audio.md
View File

@ -1,11 +1,60 @@
# Images and Audio
## Images and the texture atlas
Images need to be 'packed' before the game can use them. This preparation step needs to happen only once (as long as the original graphics are not changed).
The result one ore more a pairs of files - a texture in [png format](https://en.wikipedia.org/wiki/PNG) and a corresponding [atlas](https://en.wikipedia.org/wiki/Texture_atlas) file.
If you have a single `Images`folder, the default such pair is named `game.png`/`game.atlas`.
For your players, the individual images aren't important - only the combined images actually register to the game, so you need to include them in your repository and keep them up to date.
We still recommend including the originals in a mod, so other developers running from source can access them.
With original images included, you can use a development environment using git, have it linked to your repository, while using a symlink to allow Unciv to see the mod - and pack your atlas for you on every launch.
If you're developing your mod on an Android version of Unciv (not recommended!) you won't be able to generate these packed files directly.
### Ways to pack texture atlases
- Launch the desktop version with your mod (your mod's main folder is a subfolder of the game's "mods" folder, or symlinked there).
- You can ask someone in the Discord server to help you out.
- You can use external tools, [e.g. gdx-texture-packer-gui](https://github.com/crashinvaders/gdx-texture-packer-gui). Utmost care needs to be taken that the files can be discovered by Unciv and internal relative paths are correct.
- The Unciv repo itself has a feature that can pack images on github runners - documentation still needs to be done.
### Multiple texture atlases
If your mod has lots of images (or large ones), the textures might 'spill' into additional texture files - 2048x2048 is the limit for a single texture pack. You will see a `game2.png`, possibly a `game3.png` or more appear.
This is not good for performance, which is why the base game controls which kinds of images go together into one texture(+atlas).
This works for mods, too: Create not only one Images folder, but several, the additional ones named "Images.xyz", where xyz will become the filename of the additional texture file (So don't use both Images and Images.game - those will clash). Look at the Unciv base game to get a better idea how that works.
To minimize texture swaps, try to group them by the situation where in the game they are needed. You can distibute by folder, but having the same subfolders under several "Images.xyz" and distributing the images between them will also work.
A file `Atlases.json` (uppercase 'A') in the mod root (not in `Images` or in `jsons`) controls which atlases to load, which in turn control which texture (`.png`) files are read.
This file is automatically created by the built-in packer. Only the `game.atlas` file is read by default for backward compatibility.
If you use external tools and multiple atlases, you will need to maintain this file yourself - it is a simple json array of strings, each a file name without the `.atlas` extension (saved as UTF-8 without byte order mark).
### Texture packer settings
The texture packers built into Unciv will look for a `TexturePacker.settings` file in each `Images` directory (_not_ under `jsons`).
With this file you can tune the packer - e.g. control pixel interpolation filters.
It is a json of a [Gdx TexturePacker.Settings](https://libgdx.com/wiki/tools/texture-packer#settings) instance.
The default settings are as shown in the Gdx documentation linked above if you do supply a settings file, but without such a file, some fields have different defaults:
- `maxWidth`, `maxHeight`: 2048
- `fast`: true
- `paddingX`, `paddingY`: 8
- `duplicatePadding`: true
- `filterMin`: MipMapLinearLinear
- `filterMag`: MipMapLinearLinear unless the atlas name ends in `Icons`, then Linear.
### Texture atlas encoding
Due to certain circumstances, please make sure names and paths that will be mapped in an atlas use **only ascii**. Not all parts of the loader enforce strict UTF-8 usage, sorry.
Symptoms if you fail to heed this: mod works on a Chinese Windows box but not on a western one or vice-versa, or mod works on a Chinese Windows box but not a Chinese Linux box or vice-versa, or mod works on a Chinese Windows box with default settings but not on the same box with "Use unicode UTF-8 for worldwide language support" turned on.
This does not technically apply to the atlas name itself when multiple atlases are used (the xyz part in "Images.xyz"), but we nevertheless recommend the same rule for consistency.
## Permanent audiovisual mods
The following chapters describe possibilities that will work while a mod is ***active***.
It is either selected for the current game (during new game creation, cannot be changed after that for saved games), meaning all its rules and resources will be used.
_Or_ it is marked as 'Permanent audiovisual mod' in the mod manager (you must select it in the 'installed' column to get the checkbox).
In that case only graphics and audio will be active, the rule changes will be ignored (if it contains any) unless the first way is _also_ used.
Note that this feature includes graphics or sounds from the selected mod in _all_ games, even those started before installing the mod.
Repeat: In case of a mod bringing both changed rules and audiovisuals, the 'permanent' feature will include only the media on all games, to use the rules you will still need to select the mod for a new game.
Note that the Mod author can (and often should) control whether the checkbox appears using [ModOptions](Mod-file-structure/5-Miscellaneous-JSON-files.md#modoptionsjson) [uniques](uniques.md#modoptions-uniques).

40
docs/Modders/Mods.md
View File

@ -32,46 +32,25 @@ Mods are located in a `/mods` directory, on Desktop that should be next to your
Mods typically have 2 subfolders:
- `jsons` - here you should put files that alter the data of game objects, the order of the files is as in [the base json files](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons). More information on these can be found [here](Mod-file-structure/1-Overview.md)
- `Images` - here you should put game images, as in [the base image files](/https://github.com/yairm210/Unciv/tree/master/android/Images).
-
In order to remove objects from the game, you'll need to create a ModOptions file in the `/jsons` subfolder - there's an example [here](https://github.com/yairm210/Unciv-mod-example/blob/master/Removing%20Things/jsons/ModOptions.json)
- `Images` - here you should put game images, as in [the base image files](https://github.com/yairm210/Unciv/tree/master/android/Images).
**Base Ruleset Mods** are mods that 'start from scratch' - ALL the original objects are removed, and only the objects
In order to remove objects from the game, you'll need to create a ModOptions file in the `/jsons` subfolder - there's an example [here](https://github.com/yairm210/Unciv-mod-example/blob/master/Removing%20Things/jsons/ModOptions.json).
This is done by adding a `"isBaseRuleset":true` configuration to your [modOptions file](Mod-file-structure/5-Miscellaneous-JSON-files.md#modoptionsjson), [like so](https://github.com/k4zoo/Civilization-6-Mod/blob/master/jsons/ModOptions.json)
**Base Ruleset Mods** are mods that 'start from scratch' - ALL the original objects are removed, and only the objects of the mod in question are used.
This is done by adding a `"isBaseRuleset":true` configuration to your [modOptions file](Mod-file-structure/5-Miscellaneous-JSON-files.md#modoptionsjson), [like so](https://github.com/k4zoo/Civilization-6-Mod/blob/master/jsons/ModOptions.json).
## Audiovisual components
In addition to changing the rules - or even without doing so - mods can override existing graphics or sounds, or add music tracks. For details, see [Audiovisual Mods](Images-and-Audio.md).
Custom tilesets and unitsets are a subgroup of these - see [Creating a custom tileset](Creating-a-custom-tileset.md) - as are UI skin mods, see [Creating a UI skin](Creating-a-UI-skin.md)
Custom tilesets and unitsets are a subgroup of these - see [Creating a custom tileset](Creating-a-custom-tileset.md) - as are UI skin mods, see [Creating a UI skin](Creating-a-UI-skin.md).
Such mods are candidates for the "Permanent audiovisual mod" switch available on the Mod Management Screen.
Note that this feature includes graphics or sounds from the selected mod in _all_ games, even those started before installing the mod.
Such mods are candidates for the "Permanent audiovisual mod" switch available on the Mod Management Screen, see [Permanent audiovisual mods](Images-and-Audio.md#permanent-audiovisual-mods).
In case of a mod bringing both changed rules and audiovisuals, the 'permanent' feature will include only the media on all games, to use the rules you will still need to select the mod for a new game.
Images need to be 'packed' before the game can use them, which the desktop version can do for you. Please make sure to read the [Texture atlas](Images-and-Audio.md#images-and-the-texture-atlas) chapter!
### More on Images and the texture atlas
When running on Desktop, images are combined on game startup into a large `game.png` file with a corresponding `.atlas` file.
This means that if you're developing your mod on an Android version of Unciv (not recommended!) you won't be able to generate these images files - you can ask someone in the Discord server to help you out
For your players, the individual images aren't important - only the combined images actually register to the game, so you need to include them in your repository and keep them up to date.
Actually omitting the original images would work for these uses, but we still recommend including them, so developers running from source can access them.
#### Extremely image-heavy mods
If your mod has lots of images (or large ones), the textures might 'spill' into additional texture ".png" files - 2048x2048 is the limit for a single texture pack.
This is not good for performance, which is why the base game controls which kinds of images go together into one texture(+atlas).
This works for mods, too: Create not only one Images folder, but several, the additional ones named "Images.xyz", where xyz will become the filename of the additional texture file (So don't use both Images and Images.game - those will clash). Look at the Unciv base game to get a better idea how that works.
To minimize texture swaps, try to group them by the situation where in the game they are needed. You can distibute by folder, but having the same subfolders under several "Images.xyz" and distributing the images between them will also work.
### Adding maps to mods
## Adding maps to mods
You can also add maps to mods, so they'll be available to players who download your mod.
@ -150,4 +129,3 @@ Existing mods can be found [here](https://github.com/topics/unciv-mod)!
Now you should try to create your first mod!
We recommend you start off by [adding a new civilization](Making-a-new-Civilization.md) as a mod, to get a hang of the process :)