uncubed/spec.md

Uncubed

What is Uncubed?

Uncubed is a language designed to ease creation of Minecraft Java Edition data packs. Specifically, Uncubed focuses on simplifying the writing of mcfunction files. Simplification of JSON files for other data pack settings is out of scope, unless they support mcfunction files, typically advancements for triggers, loot tables, and predicates.

Design Goals

Uncubed is guided by the following design goals, which are to:

• Provide easy access to operations and constructs common in mainstream programming languages
• Maintain Minecraft command idioms and constructs where possible
• Significantly improve the orthogonality of Minecraft command idioms and constructs
• Reduce verbosity of data pack code
• Include only what code is necessary to support features of Uncubed which are used in the final product

Example Code

1. Define a function

function letsSay phrase {
    # Invoke the say command
    run say "Let's say " + phrase  
}

call letsSay "hi!"

2. Store x, z coordinates of selected entities as an array

set coordinates = @e[type="minecraft:sheep"].{x,z}

3. Execute if entity has property with value

if @n[type="minecraft:sheep"].Pos[0] in (50..100] {
    run say "The nearest sheep's x is greater than 50 and less than or equal to 100"
} else {
    run say "The sheep's x was not in range"
}

4.

set coordinates = @e[type="minecraft:sheep"].{x,z}[0] + @n[type="minecraft:sheep"].x

5. Filter entities

set coolEntities = entity all { type: "minecraft:sheep"

}

Specification

Data Types

Supported Types

Uncubed supports all NBT data types.

• List
• Map (represents Compound))
• Boolean
• Byte (signe,d 8-bit)
• Short (signed, 16-bit)
• Int (signed, 32-bit)
• Long (signed, 64-bit)
• Float
• Double
• String
• Byte Array
• Int Array
• Long Array

Type System

Uncubed does not use static typing. Type incompatibilities with commands will result in run-time errors. Uncubed's eventual goal is to instead produce build-time type errors where possible.

Literals are typed in the same manner as NBT literals, by using prefixes.

Expressions

Uncubed supports the use of expressions in Minecraft commands. There are two primary expression types:

• Uncubed

  These expressions use the Uncubed syntax and operators and are defined as follows:

  expression:
    <literal>
    <variable-name>
    <expression>.<path>
    <expression>[<string-or-numeric-expression>]
    <expression> <binary-operator> <expression>
    call <function> <parameters>
    <unary-operator> <expression>
    <entity-expression>
  
  path:
    <string>
  

• Entity

  These expressions use the target selector syntax. Any expression type may be used in specifying the values for use within the selector.

  Expressions using @e and @a always result in a list. All other target selectors result in a single value.

  The left-hand side of a criterion must resolve to a valid

  target-selector:
    @p
    @r
    @a
    @e
    @s
    @n
  
  entity-expression:
    <target-selector>
    <target-selector>[<selector-criteria>]
    <target-selector>[<selector-criteria>].[<path>]
    <target-selector>[]
  
  selector-criteria:
    <collection>
    <selector-criteria>,<collection>
    <collection>,<selector-criteria>
    <criterion>
    <criterion>,<criterion>
  
  collection:
    <map-expression>
    <list-of-map-expression>
  
  criterion:
    <string-expression>=<expression>
  

Variables

Variables in Uncubed are defined using the set keyword, with the following syntax:

set <variable-name> = <expression>

Expressions

Arithmetic

Uncubed provides the following operators for arithmetic:

+ - Addition - - Subtraction * - Floating-point Multiplication / - Floating-point Division \ - Integer division % - Floating-point Modulo

Call Stack

Operand Stack