diff --git a/docs/mod-wiki/modularui/json/alignment.md b/docs/mod-wiki/modularui/json/alignment.md new file mode 100644 index 0000000..3548c48 --- /dev/null +++ b/docs/mod-wiki/modularui/json/alignment.md @@ -0,0 +1,34 @@ +Alignment is an object with an x and y component. Where 0.0 means start and 1.0 means end. + +## Alignment by name + +ModularUI has 9 default alignments. + +- `top_left` or `tl` +- `top_center` or `tc` +- `top_right` or `tr` +- `center_left` or `cl` +- `center` or `c` +- `center_right` or `cr` +- `bottom_left` or `bl` +- `bottom_center` or `bc` +- `bottom_right` or `br` + +!!! Example +```json +{ + "alignment": "top_center" +} +``` + +You can also create a new alignment. + +!!! Example +```json +{ + "alignment": { + "x": 0.3, + "y": 0.6666666 + } +} +``` diff --git a/docs/mod-wiki/modularui/json/color.md b/docs/mod-wiki/modularui/json/color.md new file mode 100644 index 0000000..ea3b6c5 --- /dev/null +++ b/docs/mod-wiki/modularui/json/color.md @@ -0,0 +1,100 @@ +There are many different way to define color in JSON + +## Hexadecimal number + +The simplest way is by using hexadecimal numbers. You can do that be prefixing your number string with `0x`, `0X` or `#`. +The format is `AARRGGBB`. If `A` (alpha) is not set, it defaults to full opacity + +!!! Example + ```json + { + "color": "#FFFFFF" + } + ``` + + +The following formats can all have the `alpha` or `a` property, with a value from either 0.0 to 1.0 or from 0 to 255. +If you want to use the 0.0 to 1.0 range you need use a `.`. `1` will use the +0 to 255 range and is very low. `1.0` will use the 0.0 to 1.0 range and is full opacity. + +## RGB + +- `red` or `r`: The red value from 0 to 255 +- `green` or `g`: The green value from 0 to 255 +- `blue` or `b`: The blue value from 0 to 255 + +!!! Example + ```json + { + "color": { + "r": 200, + "g": 0, + "b": 44, + "alpha": 1.0 + } + } + ``` + +Here you can see how alpha can be added. + +## HSV + +- `hue` or `h`: The hue value from 0 to 360 (wraps around) (default is 0) +- `saturation` or `s`: The saturation from 0.0 to 1.0 (default is 0.0) +- `value` or `v`: The value from 0.0 to 1.0 (default is 1.0) + +If `value` is not defined, [HSL](#hsl) will be used. + +!!! Example + ```json + { + "color": { + "hue": 120, + "saturation": 0.5, + "value": 0.75 + } + } + ``` + +## HSL + +- `hue` or `h`: The hue value from 0 to 360 (wraps around) (default is 0) +- `saturation` or `s`: The saturation from 0.0 to 1.0 (default is 0.0) +- `lightness` or `l`: The value from 0.0 to 1.0 (default is 0.5) + +!!! Example + ```json + { + "color": { + "hue": 120, + "saturation": 0.5, + "lightness": 0.75 + } + } + ``` + +!!! Note + The saturation is not the same from [HSV](#hsv) as from [HSL](#hsl) (they are calculated slightly different), + but the hue is. + +## CMYK + +- `cyan` or `c`: The cyan value from 0.0 to 1.0 (default is 1.0) +- `magenta` or `m`: The cyan value from 0.0 to 1.0 (default is 1.0) +- `yellow` or `y`: The cyan value from 0.0 to 1.0 (default is 1.0) +- `black` or `k`: The cyan value from 0.0 to 1.0 (default is 1.0) + +!!! Example + ```json + { + "color": { + "c": 1.0, + "m": 0.5, + "y": 0.75, + "k": 0.2 + } + } + ``` + +!!! Warning + You can NOT mix any of those formats! (except of course alpha) diff --git a/docs/mod-wiki/modularui/json/drawable.md b/docs/mod-wiki/modularui/json/drawable.md new file mode 100644 index 0000000..8627310 --- /dev/null +++ b/docs/mod-wiki/modularui/json/drawable.md @@ -0,0 +1,184 @@ +This page is about defining drawables in json files. These are used in backgrounds on themes for example. + +In all examples we will use `background`. + +Drawables have a type (for example images). Each type has different properties. +For each type each property will be listed and explained. + +## Empty Drawable + +Type name: `empty` or `null` + +Empty Drawables are special since they don't need to be an object. The can juts be `null`. + +Empty Drawables don't have any properties. + +Example: + +Both definitions are equivalent. + +```json +{ + "background1": null, + "background2": { + "type": "empty" + } +} +``` + +## Images + +Type name: `texture` + +You can get an existing image with `name` or `id`. In this case all other properties will be ignored. + +```json +{ + "background": { + "type": "texture", + "id": "vanilla_background" + } +} +``` + +Or you can define a new image. An image has multiple subtypes. + +1. Full image: Uses the whole image at the given path (will be stretched to fit the render size) +2. Sub image: Uses a rectangular part of an image (will be stretched to fit the render size) +3. Adaptable image: has a border and a plain center. The border is drawn separately, so it won't be stretched no matter + how large the texture is drawn. The center should be plain because it will be stretched to fit the render size. +4. Tiled image: The image will be drawn multiples times at its original size like tiles to fit the render size. This can + be combined with adaptable image. + +For all image types you need the `location` property. It defines where the image file is. The value is a resource +location. +Check out +the [GroovyScript docs](https://groovyscript-docs.readthedocs.io/en/latest/groovyscript/rl/#converting-to-file-path) to +find out more. + +### Full image + +Full images only need the `location property`, which is explained above. + +### Sub image + +Here you want to define a rectangle inside the image. You can do that using `x`, `y`, `w`, `h`, `iw` and `ih`. All these +properties are in pixel. `w` is also `width`, `h` is also `height`, `iw` is also `imageWidth` and `ih` is +also `imageHeight`. + +Or you can define a rectangle with `u0`, `v0`, `u1` and `v1`. These are relative values from 0.0 to 1.0. `u` is the +x-axis and `v` the y-axis. 0 means start and 1 means end. + +!!! Warning +You can NOT mix both types! + +### Adaptable image + +Can be a full image or a sub image. To make an image adaptable you need `borderX` and/or `borderY` or just `border` ( +sets both axis). +`borderX` is the border size on the x-axis. All properties are in pixels. + +### Tiled image + +Can be a full image or a sub image. Can also have border properties for adaptable image. +For tiled images you need `"tiled": true` and `imageWidth` (or `iw`) and `imageHeigth` (or `ih`). + +### Example + +This is an example for an adaptable sub image (we set the values to still be the full image). + +```json +{ + "background": { + "type": "texture", + "location": "modularui:gui/background/background", + "imageWidth": 195, + "imageHeight": 136, + "x": 0, + "y": 0, + "width": 195, + "height": 136, + "border": 4 + } +} +``` + +## Colored rectangle + +Type name: `color` or `rectangle` + +Properties: + +- `cornerRadius` is the corner radius. Default is 0 +- `cornerSegments` is the amount of segments the corner has if the corner radius is not 0. Default is 6. Lower means + more pointy but faster drawing, higher means smoother but slower drawing. +- `color` is the color of the whole rectangle (see [colors](color.md)) + +We can also set colors for each corner individually. This way we can create beautiful gradients. + +- `colorTop` sets the color of the top left and top right corner. `colorBottom`, `colorLeft` and `colorRight` work + analogue +- `colorTopLeft` or `colorTL` sets the color of the top left corner. `colorTopRight`, `colorBottomLeft` + and `colorBottomRight` work analogue + +Of course, you can combine multiple colors. For example, you can set `color` and then `colorBL`. This will make all +corners +have the color of `color` except the bottom left corner which will have the `colorBL` color. + +## Ellipse / Circle + +Type name: `ellipse` + +The ellipse will always stretch to its render size. It will only be a circle if render width and render height are the +same. + +Properties: + +- `color` sets the color of the whole circle +- `colorInner` sets the center color, creating a gradient +- `colorOuter` sets the outer color, creating a gradient +- `segments` is the amount of edges the circle will have. Default is 40. Lower means more pointer and, but faster + drawing and higher means smoother and slower drawing. With low segment count you can also draw polygons + +## Text + +Type name: `text` + +Properties: + +- `text`, `string` or `key`: The text (Required) +- `lang` or `translate`: If the text is a lang key and should be translated (Default is false) +- `color`: Text color (see [color](color.md)) (Uses color of the widget theme if applicable by default) +- `shadow`: True if the text should have a shadow. (Uses shadow of the widget theme if applicable by default) +- `align` or `alignment`: The alignment of the text in the render size. (see [alignment](alignment.md)) (Default is center) +- `scale`: The scale to draw text at. (Default is 1.0) + +!!! Example + ```json + { + "type": "text", + "text": "Hello World", + "lang": false + } + ``` + +The text can also be an array. In this case the `lang` property is ignored. +Each of the elements in the array can either be a string or an object with the `text` and `lang` property. Those objects +can also have any style property like `color` and `shadow`. + +!!! Example + ```json + { + "type": "text", + "text": [ + "Hello ", + { + "text": "this.part.is.translated", + "lang": true + }, + "I18n:this.part.is.also.translated" + ] + } + ``` + +As you can see in the example above you can also start a string with `I18n:` to make it translated. diff --git a/docs/mod-wiki/modularui/json/theme.md b/docs/mod-wiki/modularui/json/theme.md new file mode 100644 index 0000000..ddd8962 --- /dev/null +++ b/docs/mod-wiki/modularui/json/theme.md @@ -0,0 +1,64 @@ + +Make sure to check out [how to register themes](../themes.md). + +Here we will take a look what the theme file can look like. If you are a mod developer you can directly translate to +your `JsonBuilder`. + +Let's look at an example. This is what the default vanilla theme as a json file would look like. + +```json +{ + "parent": "DEFAULT", + "background": null, + "hoverBackground": null, + "color": "#FFFFFFFF", + "textColor": "#FF404040", + "textShadow": false, + "panel": { + "background": { + "type": "texture", + "id": "vanilla_background" + } + }, + "button": { + "background": { + "type": "texture", + "id": "vanilla_button" + }, + "textColor": "#FFFFFFFF", + "textShadow": true + }, + "itemSlot": { + "background": { + "type": "texture", + "id": "slot_item" + }, + "slotHoverColor": "#60FFFFFF" + }, + "fluidSlot": { + "background": { + "type": "texture", + "id": "slot_fluid" + }, + "slotHoverColor": "#60FFFFFF" + }, + "textField": { + "textColor": "#FFFFFFFF", + "markedColor": "#FF2F72A8" + }, + "toggleButton": { + "background": { + "type": "texture", + "id": "vanilla_button" + }, + "textColor": "#FFFFFFFF", + "textShadow": true, + "selectedBackground": { + "type": "texture", + "id": "slot_item" + }, + "selectedHoverBackground": null, + "selectedColor": "0xFFBBBBBB" + } +} +``` diff --git a/docs/mod-wiki/modularui/themes.md b/docs/mod-wiki/modularui/themes.md index 468fc82..b559578 100644 --- a/docs/mod-wiki/modularui/themes.md +++ b/docs/mod-wiki/modularui/themes.md @@ -37,6 +37,8 @@ There are two ways to set a theme in a GUI. If both methods are used, the first will always take priority. +Checkout [this page](json/theme.md) to find out what properties you can add to the builder. + ## For resource packs First create new file in your resource pack at `assets/modularui/themes.json`. You can replace `modularui` with any @@ -71,66 +73,4 @@ Inside the curly brackets we can set themes for screens. The format is `"screen_ So in the example above `modularui:test` the full screen name and `vanilla_dark` is the theme name (which we defined before). -## Creating themes - -Here we will take a look what the theme file can look like. If you are a mod developer you can directly translate to -your `JsonBuilder`. - -Let's look at an example. This is what the default vanilla theme as a json file would look like. - -```json -{ - "parent": "DEFAULT", - "background": null, - "hoverBackground": null, - "color": "#FFFFFFFF", - "textColor": "#FF404040", - "textShadow": false, - "panel": { - "background": { - "type": "texture", - "id": "vanilla_background" - } - }, - "button": { - "background": { - "type": "texture", - "id": "vanilla_button" - }, - "textColor": "#FFFFFFFF", - "textShadow": true - }, - "itemSlot": { - "background": { - "type": "texture", - "id": "slot_item" - }, - "slotHoverColor": "#60FFFFFF" - }, - "fluidSlot": { - "background": { - "type": "texture", - "id": "slot_fluid" - }, - "slotHoverColor": "#60FFFFFF" - }, - "textField": { - "textColor": "#FFFFFFFF", - "markedColor": "#FF2F72A8" - }, - "toggleButton": { - "background": { - "type": "texture", - "id": "vanilla_button" - }, - "textColor": "#FFFFFFFF", - "textShadow": true, - "selectedBackground": { - "type": "texture", - "id": "slot_item" - }, - "selectedHoverBackground": null, - "selectedColor": "0xFFBBBBBB" - } -} -``` +Checkout [this page](json/theme.md) to find out how to write themes. diff --git a/mkdocs.yml b/mkdocs.yml index 487438d..e287edd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,6 +35,11 @@ nav: - Sizing and Positioning: mod-wiki/modularui/sizing_and_positioning.md - Framework: mod-wiki/modularui/framework.md - Themes: mod-wiki/modularui/themes.md + - Json: + - Drawables: mod-wiki/modularui/json/drawable.md + - Color: mod-wiki/modularui/json/color.md + - Alignment: mod-wiki/modularui/json/alignment.md + - Theme: mod-wiki/modularui/json/theme.md - Proposal: - Standard: - Minecraft Technical Metric System: proposal/standard/mtms.md