Themes

This section contains documentation regarding the new themes system included in SAOUI. Note that themes are in active development right now and things are subject to change. We'll try to update these pages as often as possible to reflect updates, and please share your suggestions (both regarding the content and the format of this page) in our Discord server.

Installing themes

Themes can be installed by adding a resource pack containing a theme :

This will make the theme appear in the SAOUI options, where it can be activated and deactivated at will :

Legacy themes

The mod will try it's best to load legacy-format themes. However, please understand that features and support may be limited and pack authors are advised to migrate as soon as possible to the new format described below. Please find help in our Discord server should you need it !

Authoring themes

Table of Contents

• Theme structure
• Theme metadata
• Theme localization
• Theme settings
• Theme HUD
• Theme screens
• Tips for local development

Theme structure

Note : all folders and files should use only lowercase characters, numbers and underscores as is the case with any Minecraft resource pack (AFAIK)

The basic resource pack structure is the same as for vanilla resource packs :

<pack root folder>
├── assets
│   ├── saoui_hex_new_format
│   └── wip_test_theme
├── pack.mcmeta
└── pack.png

In assets/, you can have as many folders as you want. Each of these folders will be considered a separate theme namespace similar to a modid (if it contains themes). Namespaces can contain one or more themes using the following structure :

<namespace root>
├── lang (1)
│   └── en_us.lang
├── sounds (2)
├── sounds.json (2)
├── textures (3)
│   ├── alo
│   ├── ggo
│   ├── hex
│   ├── hex2
│   ├── os
│   ├── sao
│   ├── sao_json
└── themes (4)
    ├── alo
    ├── ggo
    ├── hex
    ├── hex2
    ├── os
    ├── sao
    └── sao_json

1. lang/ contains translation files (just like regular resource packs). See here for theme-specific options.
2. sounds/ contains custom sounds. Full theme-specific support for this is not yet implemented.
3. textures/ contains custom texture files. Common practice and support for several customizations currently rely on using one folder per theme, using the theme's identifier.
4. themes/ contains one folder for each theme, with the name of the folder used as theme identifier. These folders the main theme customization files like metadata and settings :

themes
├── alo
│   ├── hud.xml
│   └── style.css
├── ggo
│   ├── hud.xml
│   └── style.css
├── hex
│   ├── hud.xml
│   └── style.css
├── hex2
│   ├── hud.xml
│   ├── settings.json
│   └── style.css
├── os
│   ├── hud.xml
│   └── style.css
├── sao
│   ├── hud-schema.xsd
│   ├── hud.xml
│   └── style.css
└── sao_json
    ├── hud.json
    └── style.css

Theme metadata

General theme metadata is yet to be developed. The plan is for it to include a few technical properties to help deliver quality themes :

• theme version
• SAOUI officially supported version(s)
• potential SAOUI addons support (along with versions)
• customization for the currently "expected paths" (see HUD and screens)

If you have other suggestions for metadata, please post them on our Discord server ;)

Theme localization

Currently, out of the box expected localization is for the theme's name and description. The following two translation keys are used by the base mod :

theme.<theme-namespace>.<theme-identifier>.name=User-friendly Theme Name
theme.<theme-namespace>.<theme-identifier>.description=User-friendly theme description

(if you need a refresher on theme namespace and identifier, please refer to the section on theme structure)

As an example, here's the current (as of writing this) theme-specific localization for the built-in themes :

theme.saoui.alo.name=ALO
theme.saoui.alo.description=Built-in theme inspired by ALfheim Online
theme.saoui.ggo.name=GGO
theme.saoui.ggo.description=Built-in theme inspired by GunGale Online by Blaez
theme.saoui.hex.name=Hex
theme.saoui.hex.description=Built-in dark theme using hexagonal geometry by Genetyx8
theme.saoui.hex2.name=[WIP] Hex2
theme.saoui.hex2.description=[WIP] Built-in experimental variant of the Hex theme using WIP features
theme.saoui.os.name=OS
theme.saoui.os.description=Built-in theme inspired by Ordinal Scale by Blaez
theme.saoui.sao.name=SAO
theme.saoui.sao.description=Built-in theme inspired by SAO (the original theme of the mod)
theme.saoui.sao_json.name=[WIP] SAO
theme.saoui.sao_json.description=[WIP] Built-in experimental variant of the SAO theme using JSON hud

Since they're built into the SAOUI mod, we defined all of them in the saoui namespace (which matches the modid). Each theme uses a recognizable acronym used to clearly distinguish theme-specific resources in the pack by their folder name. Note again that both have to be made up of lowercase characters, numbers and underscores.

Theme settings

(TODO)

Theme HUD

(TODO)

Theme screens

(TODO)

Tips for local development

(TODO)