Skip to content

Element Types

Jump to bottom
AlexIIL edited this page May 28, 2021 · 11 revisions

Element Types, for 1.12.2:

Resource Locations

Minecraft uses "Resource Locations" to identify files. These are in the form "<namespace>:<path>", and load from the path "assets/<namespace>/<path>". If the name is ommitted then it usually defaults to "minecraft", except for references, which default to "customloadingscreen"

References

A few of the fields may be references rather than their actual objects. These should be strings (such as "config/test/image_background") rather than their objects. CLS automatically modifies references in the following ways:

  • If a reference doesn't start with a namespace then it uses "customloadingscreen" as it's default namespace instead of "minecraft".
  • If a reference starts with "sample/", then it is changed to "<namespace>:sample/<type>/<path>.json"
  • If a reference starts with "config/" then it loads from "<minecraft-directory>/config/customloadingscreen/<type>/<path>.json" rather than looking through resource packs.
    • If the reference is to a config then it's type is ommitted.
  • Otherwise it will be changed to "<namespace>:<type>/<path>.json"

Config

A json object, where all of these fields must be present:

  • "renders": an array of RenderingPart (or references to them)
  • "factories": an array of Factory (or references to them)
  • "actions": An empty array. (Actions haven't been implemented yet).

Plus any of these optional fields:

  • "parent": a string, pointing to a Config. Fields in the parent will be added before any fields in the existing array.
  • "variables": An object of Variable
  • "constants": An object of Constant
  • "functions": an object of Function

RenderingPart

Rendering parts are json objects, which may have any of the following fields:

  • "parent": a string, pointing to a RenderingPart. Fields in the parent will be used if they aren't declared here.
  • "image": a Render (or references to them)
  • "should_render": an expression, which is evaluated every frame to see if this RenderingPart should display. Defaults to "true".
  • "instructions": An array of Instruction (or references to them).

NOTE: Unlike every other type in CLS you can reference "Render"s directly - you don't have to create a RenderingPart json if you don't need any of it's functionality. This doesn't apply if you define a RenderingPart in the config json file though.

Render

Renders are the most important part of CLS: they actually define renders. The first field should be "parent", and it picks what the render should actually be. Alternatively this can reference a Render, which will determine the type instead.

There are the following types:

  • "builtin/text" (Text)
  • "builtin/image" (Image)
  • "builtin/slideshow" (Slideshow)
  • "builtin/panorama" (Panorama)

Shared fields.

All renders (except for panoramas) use the following fields:

  • "position": an object, with 4 fields: "x", "y", "width", and "height". (text doesn't use "width" or "height", as that is calculated when rendering the text).
  • "position_type": 2-part string, separated by an underscore "_"
    • The first element may be "TOP", "CENTER", or "BOTTOM", and affects the "y" component".
    • The second element may be "LEFT", "CENTER", or "RIGHT", and affects the "x" component.
    • If both are "CENTER", then you should just use "CENTER", rather than "CENTER_CENTER"
    • Note that these must be uppercase at the moment.
  • "offset_pos": uses the same options as "position_type".

These are used to translate the render itself. This is accomplished by using a "Translate" instruction based on the screen width and height (for "position_type"), and the element width and height (for "offset_pos")

  • "TOP" and "LEFT" do not affect the components at all.
  • "CENTER" applies:
    • for "position_type": "( screen_width ) / 2 + ( value )"
    • for "offset_pos": "-( elem_width )/2"
  • "BOTTOM" and "RIGHT" apply:
    • for "position_type": "( screen_width ) + ( value ) "
    • for "offset_pos": "- (elem_width )"

(For "y", CLS uses "height" instead of "width")

Generally if you want an element to be aligned to a particaulr side then you should use the same value for both. However if you wanted several rows of text to be on the right side, but aligned together on the left, then you would use a "position_type" of "CENTER_RIGHT" but an "offset_pos" of "TOP_LEFT".

Text

These have the following fields:

Image

Slideshow

Panorama

Constant and Variable

Constants and variables are declared in a very similar manor, however constants are parsed and loaded before functions, and variables are loaded afterwards.

Both are specified in two strings, the first being the name, and the second being the value. The name must not contain spaces. The value is parsed as an expression, which is then evaludated exactly once for constants, and once per frame for variables.

You can change a variable declaration to a constant by prefixing the name with either "constant " or "const", and you can change a constant declaration to a variable by prefixing it with "variable ".

For example the sample config "slideshow" has the following consatnt block:

"constants": {
    "image_interval": 3.0,
    "transition_duration": 0.5,
    "tip_interval": 8.0,
    "random_slide_order": false,

    "tip_seed": "generate_seed()",
    "slideshow_seed": "generate_seed()"
}

Function

Functions are declared in two parts: the name&args, and the value.

The name and arguments should be in the following form: "name(argType1 argName1, argType2 argName2)". Arguments are availible to use as variables in the expression. For more information on both availible argument types and expressions please go here (todo: add link and write page)

For example the sample config "slideshow" has the following functions block:

"functions": {
    "slideshow_frame_inner(float timeSub)": "floor((time - timeSub) / image_interval)",
    "slideshow_frame(float timeSub, int count)": "random_slide_order ? ( random_int( slideshow_seed, slideshow_frame_inner(timeSub), count ) ) : slideshow_frame_inner(timeSub)"
},
Clone this wiki locally