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

The <type> will be mapped slightly differently than the names used here, instead:

  • Config uses config
  • RenderingPart uses imagemeta
  • Render uses image
  • Instruction uses instruction
  • Factory uses factory

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, but for some unknown reason CLS still needs them).

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)

Render-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.

Render-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.

Render-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))

Render-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).

Render-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.

Instruction

These are optional "instructions" that you can attach to a Render in order to change it's functionality. Like renders, there are several built-in types that all instructions must have as their parent:

  • builtin/translate (Translate)
  • builtin/scale (Scale)
  • builtin/rotate (Rotate)
  • builtin/colour (Colour) - mostly unnecessary.

Instruction-Translate

This has 2 require fields (x and y) and one optional field (z). Each field offsets the relevant component of the main Render by the specified number of pixels (although you can use decimals)

Instruction-Scale

Like Translate, x and y are required, and z is optional. This multiplies the size of the relevant component of the main Render by the given amount.

Instruction-Rotate

This has 1 mandatory field:

  • angle: Indicates the angle to rotate by.

And 3 optional fields: x, y, and z. All of them default to 0.

These are interpreted as multipliers for angle. To rotate a 2d object on screen you should set z to 1, and then use the angle field to actually rotate.

Instruction-Colour

This is a mostly-internal instruction: you can't use this to override the colour already specified in a Render, so there's no reason to use this yet. (Even if colour is not specified by the render, this still doesn't do anythng).

Factory

Currently there's only 1 builtin type: builtin/change (Change). As such the parent must be set to this, or a factory that extends it.

Factory-Change

This has the following optional fields:

  • change: The value to check for changes.
  • to_create: Either an array of, or a single, RenderingPart.
  • should_destroy: An expression which is evaluated per-element per-frame, which indicates wheteher that element should be removed or not.
  • kept_variables: An array of Variable which each element will keep a unique copy of when it is created.
  • variables: An arry of Variable which are shared between all factory elements.

! TODO: DOCUMENT THIS !

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