Skip to content

Element Types

Jump to bottom
AlexIIL edited this page May 29, 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 Renders 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:

  • colour: An expression, which should result in an (integer) colour in the form 0xAA\_RR\_GG\_BB (in hexidecimal notation)
  • 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:

  • text: An expression for the actual text to display
  • scale: The scale to display the text at. Integer values are recommended, but you can use decimals if you need to. Defaults to 1.
  • image: The font texture to use to display the text. Defaults to minecraft:textures/font/ascii.png.

Image

  • image: The image to load. Can be a GIF rather than a still image.
  • texture: The area to take from the source image:
    • This is an object with the following fields: x, y, width, height.
    • All fields wrap around below 0 and above 1, where 0 refers to the top left of the texture and 1 refers to the bottom right of the texture.
  • frame: If the image is animated then this is allows CLS to switch between them. Defaults to time (at least right now, future versions might default to playing the gif at 1x speed rather than 1 frame per second).
  • loop: If true then the real frame will be frame % frame\_count, and if false then the real frame will be max(0, min(frame\_count, frame))

Slideshow

This inherits all of the fields in Image except for loop.

  • image: The images to load. Every # in this will be replaced with the slideshow index, from 0 up to 999. 1.5.1 and later stops loading slideshow images whenever one of them is missing. (Except for 0, which is skipped if it is missing).
  • frame: This is redefined to be the slideshow index, rather than the animation index in the gif. (slieshow doesn't support gifs at the moment).

Panorama

This displays a panorama similar to the one seen in the main menu,

  • image: The images to load. If this contains \_x then it will be replaced with [ \_0, \_1, \_2, \_3, \_4, and \_5 ] for the six sides of a cube. This mirrors vanilla's main menu format.
  • angle: The angle to rotate the panorama by, in degrees. This defaults to time * 40.

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