JfMods/Respackopts
JfMods
/
Respackopts
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[docs] Add page on changes between pack format versions

This commit is contained in:
Johannes Frohnmeyer 2022-02-19 15:10:53 +01:00
parent 2e4cc36303
commit 29d5288707
Signed by: Johannes
GPG Key ID: E76429612C2929F4
15 changed files with 143 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
docs/AdvancedConditions.md Normal file
View File

@ -0,0 +1,87 @@
# Advanced Conditions
Respackopts uses "conditions" for deciding what files to load.
Respackopts conditions are usually a simple string with a pack and entry name
(IE `<pack id>:<entry name>` or `<entry name>`),
however, respackopts provides various additional features to enhance their functionality.
This page will go over everything you can do with conditions
## (Boolean) logic
Any JSON object will be treated as a logical condition.
This behavior allows defining resources that are only used when a set of conditions are met,
not just one. Be aware that nesting logic operations is supported and recommended for advanced setups
The following expressions are supported:
| Example | Explaination |
|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `{"not": "examplePack:condition1"}` | True if the contained condition is false |
| `{"and": ["examplePack:condition1", "examplePack:condition2"]}` | True if all contained conditions are true |
| `{"or": ["examplePack:condition1", "examplePack:condition2"]}` | True if any contained condition is true |
| `{"nor": ["examplePack:condition1", "examplePack:condition2"]}` | True if none of the contained conditions are true |
| `{"xor": ["examplePack:condition1", "examplePack:condition2"]}` | True if the number of contained conditions which are true is an odd number |
| `{"eq": ["examplePack:condition1", "examplePack:condition2"]}` | True if all contained conditions have the same value <br>(equivalent to `{"or": [{"and": [...]}, {"nor": [...]}]}`) |
## Built-in conditions
Respackopts provides some conditions by default, you can use them in any pack.
| Condition | Explaination |
|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `modversion:<mod>:<predicate>` | True if the specified mod is loaded (use the mod ID) and the version fits the predicate.<br>Example: `modversion:minecraft:>=1.7.10`, `modversion:continuity:*` |
## Fabric Resource Conditions Interop
Fabric API provides a system called resource conditions, which is similar to respackopts own system.
To improve compatibility, respackopts allows accessing fabric resource conditions and respackopts conditions from one another.
### Fabric Resource Conditions from Respackopts
A json object containing a singular entry whose key is `fabric:load_conditions` will be treated as a Fabric Resource Condition.
Example:
```json
{
"condition": {
"fabric:load_conditions": {
"condition": "fabric:not",
"value": {
"condition": "fabric:all_mods_loaded",
"values": [
"a"
]
}
}
}
}
```
### Respackopts conditions from Fabric
You may access respackopts conditions from Fabric API Resource Condition blocks by specifying a condition with the ID
`config`. Its value will be treated as a respackopts condition.
Please be aware that fabric resource conditions are not tied to resource packs and entry IDs must therefore be specified fully.
(Using `someTexture` instead of `examplePack:someTexture` is impossible)
Example:
```json
{
"type": "minecraft:crafting_shapeless",
"ingredients": [
{
"item": "minecraft:stick"
}
],
"result": {
"item": "minecraft:diamond"
},
"fabric:conditions": [
{
"condition": "fabric:not",
"value": {
"condition": "respackopts:config",
"value": {
"and": [
"examplePack:someTexture"
]
}
}
}
]
}
```

10
docs/AdvancedConfig.md
View File

@ -4,11 +4,11 @@
Every advanced entry will be represented as a json object.
Every entry can contain the following properties, regardless of its type:
| Name | Required | Description |
| --- | --- | --- |
| type | yes | The type of the entries. Each one can contain specific info, more on that below |
| default | yes | The default value for this entry. This is what you would specify in a normal config entry (except for enums, where this is just the default entries name) |
| reloadType | no | `"Resource"` or `"Simple"`, specifies whether resources have to be reloaded if this is changed. Frex shaders will be reloaded anyways |
| Name | Required | Description |
|------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | yes | The type of the entries. Each one can contain specific info, more on that below |
| default | yes | The default value for this entry. This is what you would specify in a normal config entry (except for enums, where this is just the default entries name) |
| reloadType | no | `"Resource"` or `"Simple"`, specifies whether resources have to be reloaded if this is changed. Frex shaders will be reloaded anyways |
## Numbers
There are two ways to display numbers: input boxes and sliders.

12
docs/Debugging.md
View File

@ -2,33 +2,33 @@
If you run into issues with respackopts and cannot find a solution here,
you may contact me through my discord server (look at the mod page)
### Look at the config file
## Look at the config file
Respackopts stores configurations next to their corresponding resource packs (`some pack.zip.rpo` usually)
This file contains all applied config options as saved by respackopts.
### Dump the internal representation
## Dump the internal representation
Running `/rpo dump config` will dump all data available about the enabled packs, including their config options (but not individual configurations like .rpo files)
You can use this if a conf.json isn't working as expected
### Dump GLSL code
## Dump GLSL code
You can run the command `/rpo dump glsl` to dump the shader code generated by respackopts to a file.
I recommend reading through it if your shader is misbehaving.
The content imported to your shader by the integrations will equal the dumped code.
### Verify that the option you are using exists
## Verify that the option you are using exists
One common issue is that you removed an option but still use it somewhere.
The log will usually reference that option and the source.
### Ensure you are using the correct dots
## Ensure you are using the correct dots
Ensure conditions follow one of the following conventions.
Using dots, colons or commas where they don't belong will break your pack:
- `<pack id>:<entry id>`, eg `breeze16:bushyLeaves.full`
- `<entry id>`, eg `bushyLeaves.full`
### Avoid infinite loops
## Avoid infinite loops
Ensure that you do not reference an original file or a previous fallback from a fallback.
Respackopts WILL crash if it runs into an infinite loop!

54
docs/FabricResourceConditions.md
View File

@ -1,54 +0,0 @@
# Fabric Resource Conditions
## Fabric Conditions from Respackopts
A json object containing a singular entry whose key is `fabric:load_conditions` will be treated as a Fabric Resource Condition.
Example:
```json
{
"condition": {
"fabric:load_conditions": {
"condition": "fabric:not",
"value": {
"condition": "fabric:all_mods_loaded",
"values": [
"a"
]
}
}
}
}
```
## Respackopts conditions from Fabric
You may access respackopts conditions from Fabric API Resource Condition blocks by specifying a condition with the ID
`config`. Its value will be treated as a respackopts condition.
Please be aware that fabric resource conditions are not tied to resource packs and entry IDs must therefore be specified fully.
(Using `someTexture` instead of `examplePack:someTexture` is impossible)
Example:
```json
{
"type": "minecraft:crafting_shapeless",
"ingredients": [
{
"item": "minecraft:stick"
}
],
"result": {
"item": "minecraft:diamond"
},
"fabric:conditions": [
{
"condition": "fabric:not",
"value": {
"condition": "respackopts:config",
"value": {
"and": [
"examplePack:someTexture"
]
}
}
}
]
}
```

4
docs/MainConfig.md
View File

@ -1,6 +1,6 @@
# Creating a Screen
### Before we begin
## Before we begin
Any pack id or config entry name MUST only contain alphabetical characters (no numbers, spaces, underscores, etc) and SHOULD be in [camelCase](https://en.wikipedia.org/wiki/Camel_case).
If that is not the case, you may face unexpected issues.
You can add [translations](./Translations.md) to work around this in the UI shown to users though.
@ -11,7 +11,7 @@ You can add [translations](./Translations.md) to work around this in the UI show
### Location (DataPacks).
> `/data/respackopts/conf.json`
## What needs to be here.
### What needs to be here.
```json
{
"id": "<PackID>",

12
docs/Migrations.md
View File

@ -5,7 +5,7 @@ which will continue to use the old version.
This page lists the changes relevant to pack developers between versions and migrations (if needed)
### v1
## v1
Corresponds to version 1.0 - 1.4.4
- FREX Shader support
@ -18,21 +18,21 @@ Corresponds to version 1.0 - 1.4.4
- Tooltips: `respackopts.tooltip.<pack>.<entry>`
- Boolean conditions (and, or, nor, xor, equals): `{"<type>":[<entry 1>, <entry 2>]}`
### v2
## v2
Corresponds to version 2.0.0 - 2.2.0
- Removed LibCD compat
- Enum: define enum entries as booleans if they are selected, not their numerical value
- Further shader entry name sanitization
### v3
## v3
Corresponds to version 2.3.0
- `respackopts.title.<pack>` to `rpo.<pack>`
- `respackopts.field.<pack>.<entry>` to `rpo.<pack>.<entry>`
- `respackopts.tooltip.<pack>.<entry>` to `rpo.tooltip.<pack>.<entry>`
### v4
## v4
Corresponds to version 2.4.0 - 2.5.0
- Resource expansion support
@ -40,13 +40,13 @@ Corresponds to version 2.4.0 - 2.5.0
- Allow using singular names and allow using a single entry instead of an array (`fallbacks` to `fallback`, `conditions` to `condition`, `expansions` to `expansion`)
- Remove requirement for specifying pack id in conditions: `<pack>:some.entry` to `some.entry`
### v5
## v5
Corresponds to version 2.6.0 - 2.7.1
- Pack capabilities, no longer includes DirFilter for new packs by default
- Add /rpo command for debugging
### v6
## v6
Corresponds to version 2.7.2 - 2.9.1
- allow specifying entries as objects with additional properties (`type`, `default`, `reloadType`)

23
docs/MultipleFileSelection.md
View File

@ -10,21 +10,14 @@ You will need to navigate to the file you would like to toggle inside your resou
<br>
### Examples:
`texture.png` would be `texture.png.rpo`<br>
`some_recipe.json` would be `some_recipe.json.rpo`
<br>
### `.rpo` explaination :
You need a `.rpo` file per texture (except for the last one in your list) if you have 3 files to select beteen then you will need 2 `.rpo` files, If you have 4 files to select between then you will need 3 `.rpo` files and so on etc.....
`some_recipe.json` would be `some_recipe.json.rpo`<br>
### `.rpo` explanation :
You need a `.rpo` file per texture (except for the last one in your list) if you have 3 files to select beteen then you will need 2 `.rpo` files, If you have 4 files to select between then you will need 3 `.rpo` files and so on etc...
### Layout:
This is your first `.rpo` with your first file
This is your first `.rpo` with your first file:
```json
{
"condition": "<your pack id>:<your entry>",
@ -32,10 +25,7 @@ This is your first `.rpo` with your first file
}
```
***
This is your second `.rpo` with your second file
This is your second `.rpo` with your second file:
```json
{
"condition": "<your pack id>:<your entry>",
@ -43,8 +33,7 @@ This is your second `.rpo` with your second file
}
```
### Example:
### Example:
```json
{
"condition": "examplePack:option_one",

28
docs/README.md
View File

@ -2,25 +2,25 @@
Here is everything you need to know about configuring your resource with respackopts.
Some pages may not have been updated, you can view those [here](old/)
### Compatibility
## Compatibility
- Fabulous/Canvas/Frex Shaders
- Resource Packs
- DataPacks
### Features
| Feature | Status |
| --- | --- |
| Boolean (toggle) inputs | ✅ |
| Slider inputs | ✅ |
| Number inputs | ✅ |
| String (Text) inputs | ✅ |
| Conditional file loading | ✅ |
| Fallback files | ✅ |
| Not, And, Or, Nor, Xor, Eq Operations for conditions | ✅ |
| Text file modification using [Starscript](https://github.com/MeteorDevelopment/starscript/wiki) | ✅ |
| Directory .rpo support | 🔄 |
## Features
| Feature | Status |
|-------------------------------------------------------------------------------------------------|--------|
| Boolean (toggle) inputs | ✅ |
| Slider inputs | ✅ |
| Number inputs | ✅ |
| String (Text) inputs | ✅ |
| Conditional file loading | ✅ |
| Fallback files | ✅ |
| Not, And, Or, Nor, Xor, Eq Operations for conditions | ✅ |
| Text file modification using [Starscript](https://github.com/MeteorDevelopment/starscript/wiki) | ✅ |
| Directory .rpo support | 🔄 |
### Packs using Respackopts
## Packs using Respackopts
This list doesn't include all packs using respackopts, just some I know of.
If you want your pack added/removed from here, you can open a PR

6
docs/Shaders.md
View File

@ -2,9 +2,9 @@
## Getting started
All you need to do to access respackotps values is paste the following in a file where you want them according to your renderer:
| Renderer | Include snippet |
| --- | --- |
| Canvas | `#include respackopts:config_supplier` |
| Renderer | Include snippet |
|------------------|-------------------------------------------------------------------------------------------------------------------|
| Canvas | `#include respackopts:config_supplier` |
| Vanilla/Fabulous | `//include respackopts:config_supplier` (this is done to avoid problems when loading shaders without respackopts) |
However, usually you will want to still have a pack that works if respackotps is not present. In that case, canvas will still load the file,

14
docs/ToggleFiles.md
View File

@ -1,5 +1,4 @@
# Toggle Files
This is a simple `IF` statement simply returning true/false to if the texture/file should be loaded into the pack.
(Turns the texture "on" or "off").
You will need the `Pack ID` and `Entry Name` from your `/assets/respackopts/conf.json` that you created earlier
@ -27,11 +26,14 @@ You will need to navigate to the file you would like to toggle inside your resou
}
```
### Built-in conditions
Respackopts provides some conditions by default, you can use them in any pack.
For more information on conditions, [read this](./AdvancedConditions.md)
| Condition | Explaination |
| --- | --- |
| `modversion:<mod>:<predicate>` | True if the specified mod is loaded (use the mod ID) and the version fits the predicate. Example: `modversion:minecraft:>=1.7.10`, `modversion:continuity:*` |
### Toggle Directories
Directories ("Folders") can also be toggled without toggling individual files.
To do this, create a file in the directory you want to toggle titled `.rpo` (no file name).
Both conditions and fallbacks work like they do on files, however, specifying multiple fallbacks
for a directory will not work. In some cases, you may need to add `"DirFilterAdditive"`
to your `"capabilities"` inside your conf.json for fallbacks to work as expected.
Please be aware that you should NOT specify it unless you are SURE you need it, as it will worsen performance.
See [Switch between two files](./ToggleFilesWithFallback.md) to see how to swap textures out with each other (alternate Options)

2
docs/ToggleFilesWithFallback.md
View File

@ -28,7 +28,7 @@ You will need to navigate to the file you would like to toggle inside your resou
}
```
### Another way to do this:
## Another way to do this:
Respackopts supports specifying multiple possible fallbacks when configuring single files.
You can use this functionality as follows:
```json

2
docs/Translations.md
View File

@ -30,6 +30,8 @@ This works similarly to changing the title, however, the name of the entry is ap
```
This example would set the text of the entry named `someTexture` in the pack with the id `examplePack`. Categories work the same way as they do in .rpo files and everywhere else: you use `categoryName.entryName` instead of `entryName`.
Enum entries ("Select From a list") can be translated using `rpo.<pack id>.<entry id>.<entry>`, for example `"rpo.examplePack.someOption.optionOne": "Option One"`
## Adding a tooltip to an entry
The translation system also enables you to add tooltips (small pieces of text that are shown only if the users' mouse cursor is above the option) to config options. The syntax for these is as follows: `rpo.tooltip.<PackID>.<Entry Name>`.
Example:

5
docs/old/README.md
View File

@ -3,7 +3,4 @@ The pages here are for reference and may include information not present in the
However, the quality of the documentation here is worse.
## Migration status
| Page | Status |
| --- | --- |
| [conditional](conditional.md) | TODO explain advanced conditions/condition arrays |
| [expand](expand.md) | TODO |
All documentation except that for resource expansion has been migrated.

44
docs/old/conditional.md
View File

@ -1,44 +0,0 @@
# Conditional Resources
Conditional resources are the simplest use case of respackopts.
To add one, you will need to create an rpo file for your resource.
It needs to be titled by appending `.rpo` to the files name.
For example: If you want `/assets/minecraft/lang/en_us.json` to be configurable, you will need to create `/assets/minecraft/lang/en_us.json.rpo`
If you only want a simple condition, you can use the following template:
```json
{
"conditions": [
"<your pack id>:<your entry>"
]
}
```
You can simply copy the id from your conf.json. The entry will be the name of the entry for things directly under `conf`,
otherwise it will be `category.entry`. For nested categories, names will follow the same schema.
If you have an enum entry ("Select from list"), it will be `category.entry.option`
## Logic
You may also use logic to determine whether conditions are met.
This might look like the following example:
```json
"conditions": [
"example:option1",
{
"or": [
"example:option2",
"example:option3",
{
"and": [
"example:option4",
"example:option5"
]
}
]
}
]
```
The following conditions are supported:
| Name | Function |
--|--
| and | True if all sub-conditions are met |
| or | True if at least one sub-condition is met |
| xor | True if an uneven number of sub-conditions is met |
| nor | True if none od the sub-conditions are met |
| eq | True if all the sub-conditions have the same result |

4
mkdocs.yml
View File

@ -6,7 +6,7 @@ theme:
- glsl
site_dir: public
repo_url: https://gitlab.com/jfmods/respackopts
site_description: Documentation for the respackotps config engine for minecraft resource and data packs
site_description: Documentation for the respackopts config engine for minecraft resource and data packs
site_author: JFronny
nav:
- 'README.md'
@ -20,8 +20,8 @@ nav:
- 'ToggleFilesWithFallback.md'
- 'MultipleFileSelection.md'
- 'Additional':
- 'AdvancedConditions.md'
- 'Shaders.md'
- 'FabricResourceConditions.md'
- 'Migrations.md'
- 'Old wiki':
- About: 'old/README.md'