Kinds

The sort of thing an object is.

Introduction

CraftScript has no real concept of a 'type' in the sense that most programming languages do.

An object can be anything (text, a number, a player) or nothing at all.

In fact, objects are regularly mutated internally while code is running.

CraftScript introduces the concept of a kind to determine what you can (and can't) do with an object.

A kind is the kind of thing an object is.

A kind is a family of co-occurring properties that may be employed for the purposes of inference or explanation.

What kind of thing is a list? Well, it's the kind of thing that has a size, that is either empty or not empty, that contains elements, that can have elements added to or removed from it.

What Does a Kind Do?

Every object has properties, which you access via the %object%[%property%] syntax.

Even null has a singular property (type).

CraftScript uses an object's kind to determine what properties are available and, when a script asks for or tries to change one of these properties, what should happen.

In this example we have an object player, whose name property we ask for.

player = @s
/say {player[name]}

What kind of a thing is player?

It comes from the self-selector @s, which retrieves the user running the script.

This could be a Minecraft player, or it could be the server console, or a zombie, or something else.

What the name property means depends on what kind of thing player is.

If the script knows what player's kind is then it will use this to determine what name means. If it does not know it will first attempt to determine what kind of object player is.

A kind is also used to determine what to print when an object is interpolated into text. If a number value 10 is treated as the #number decimal kind, it will print as 10.0, whereas if it is treated as the #integer whole number kind, it will print as 10.

Conversion Between Kinds

Kind Treatment

Some objects can be treated as one kind of thing or another. A Minecraft player can be treated as a #commandsender, a #player or an #entity.

While most kinds like these will inherit from one another (e.g. players have all properties that command senders do, plus some additional functions) there are occasions where we might have an object that is both a kind of #x and a kind of #y, but these are separate kinds with no overlap.

In this case we can use the convert property function of a kind to obtain it as either #x or #y.

require [object]
x = run #x[convert] object
y = run #y[convert] object

In the above example, where object is already an #x and a #y, our new x and y variables both contain the same object: affecting the object x is the same as affecting the object y. The difference between the two variables is that x is able to use properties from the X-kind, whereas y is able to use properties from the Y-kind.

Kind Transformation

Alternatively, there may be cases where an object needs to be treated as a different kind of thing, which it resembles but is not directly compatible.

Locations and vectors are both similar kinds of things: both can have x, y and z coordinates, both have a technical magnitude, but each has properties that the other lacks.

That said, locations and vectors resemble each other closely enough that we can convert one to the other.

require [location]
vec = run #vector[convert] location
loc = run #location[convert] vector

List of Kinds

This is the list of built-in kinds. Domains can register additional kinds or remove existing ones.

All objects have a type property, which returns the #kind of the object. Kind-specific properties are listed below. Some kinds inherit properties from another kind (e.g. integers are a kind of number).

String

Text.

Property	Description
length	The length of the text.
is_empty	Whether the text is empty.
is_blank	Whether the text has only whitespace.
lowercase	A lowercase copy of the text.
uppercase	An uppercase copy of the text.
char_at	fn(x) -> Character at x.
substring	fn(x) -> The text after index x. fn(x, y) -> The text between indices x and y.
index_of	fn(x) -> The position of text x in the text.
starts_with	fn(x) -> Whether the text starts with x.
ends_with	fn(x) -> Whether the text ends with x.
contains	fn(x) -> Whether the text contains x.
matches	fn(x) -> Whether the text matches x.

Number

A numerical value.

Property	Description
integer	This number as an integer.
decimal	This number as a decimal.
abs	The absolute (positive) value of this number.
sqrt	The square root of this number.
floor	This number, rounded down.
ceil	This number, rounded up.
round	This number, rounded.

Integer

A whole number value.

Integers inherit from numbers.

The integer, floor, ceil and round properties all return this value.

Void

The empty, null value.

The empty has no properties.

Library

A library object. Typically the result of importing a library (e.g. math).

Property	Description
properties	All of the properties available from this library.
<property>	A library-specific property.

Kind

A kind-reference (e.g. #string)

Property	Description
name	The actual name of the system resource.
path	The actual path of the system resource.
properties	All properties available.
is_array	Whether this represents a multi-object array.
is_flag	Whether this represents a flag.
values	All possible values of this type. This only works for flags.
is_instance	fn(x) -> Whether x is this kind of object.
convert	fn(x) -> Attempts to transform x into whatever kind of thing this is.

Flag

A special type of data that can be one of a fixed set of flags.

Flags have a set of pre-defined possible values.

Property	Description
name	This flag's uppercase name.
index	The index of this flag in the list of all possible flags.

Collection

A group of several values that can be looped in a for statement.

Property	Description
size	The number of objects in the collection.
is_empty	Whether the collection contains no objects.
clone	A duplicate of this collection.
contains	fn(x, ...) -> Whether this contains the arguments.
remove	fn(x, ...) -> Removes the arguments from this.
add	fn(x, ...) -> Adds the arguments to this.
retain	fn(x, ...) -> Removes everything except these arguments.

List

A list of objects.

A list is a collection that remembers its order. A list inherits all properties of a collection.

Property	Description
index_of	fn(x) -> The index of object x in this.
get	fn(x) -> The object at index x in this.
set	fn(x, y) -> Sets the object at index x to value y.

Map

A key <-> value map of objects.

Property	Description
size	The number of entries in this.
keys	A list of keys in this.
values	A list of values in this.
<key>	The value attributed to that key. Can be set.

Structure

A user-created object with mutable properties.

Property	Description
properties	All of the properties available from this object.
<property>	The value of this property. Can be set.

Event

An event object.

Different events may provide different property sets.

Property	Description
entity	The entity triggering the event.
location	The location of the event.
<property>	A property, provided by the individual event.

Executable

An executable object, which can be triggered with the run statement.

Property	Description
debug	Prints a text version of this.

Statement

An exectutable object, usually (part of) a line from a script.

Statements inherit all properties of executables.

Vector

An (x, y, z) vector, representing an offset from (0, 0, 0).

Property	Description
length	How far this is from the origin.
length_squared	The length, without a square root.
x	The x coordinate of this. Can be set.
y	The y coordinate of this. Can be set.
z	The z coordinate of this. Can be set.
clone	A copy of this.
is_zero	Whether this is (0, 0, 0).
is_normalized	Whether the length of this is 1.
distance	fn(x) -> How far this is from vector x.
distance_squared	fn(x) -> How far this is from vector x, without a square root.
angle	fn(x) -> The angle between this and vector x.

Location

An (x, y, z) position in a Minecraft world. May also contain a yaw and pitch angle.

Property	Description
length	How far this is from the origin.
length_squared	The length, without a square root.
x	The x coordinate of this.
y	The y coordinate of this.
z	The z coordinate of this.
yaw	The horizontal rotation.
pitch	The vertical rotation.
clone	A copy of this.
chunk	The chunk this is inside.
block	The block at this position.
is_loaded	Whether this position is loaded.
is_generated	Whether this position is generated.
to_vector	A vector of this position's coordinates.
direction	A vector of this position's rotation.
distance	fn(x) -> How far this is from location x.
distance_squared	fn(x) -> How far this is from location x, without a square root.

Material

Represents a Minecraft material type (e.g. stone, oak_planks). This is a discrete universe of values.

This inherits all properties of flags.

There are more than a thousand possible materials, so it is unwise to ask for all material values unless necessary.

Property	Description
is_occluding	Whether this would occlude light.
is_air	Whether this represents air.
is_empty	Whether this is an empty block.
is_block	Whether this is a block material.
is_burnable	Whether this would be consumed by fire.
is_collidable	Whether an entity can collide with this.
is_fuel	Whether this can power a furnace.
is_flammable	Whether this can catch fire.
is_interactive	Whether this can be interacted with.
is_edible	Whether this can be eaten.
is_item	Whether this is an item a player could hold.
is_record	Whether this is a music disc.
is_solid	Whether this is a solid block.
equipment_slot	The equipment slot this goes in (e.g. hand).
max_stack_size	The maximum amount of this that fits in a slot.
max_durability	The durability of this (if equipment).
block_data	Converts this to a block state.
blast_resistance	The blast resistance of this.
hardness	The break resistance of this.
slipperiness	How slippery this is to walk on.
rarity	How rare this is to find.
category	The category of this material.
gravity	Whether this falls when placed as a block.
key	The resource key of this material.
id	The numerical ID of this material.

Block State

The property states of a block in the world. This represents what a block could be (e.g. waterlogged slab) rather than a specific block.

This inherits all the properties of a material.

Property	Description
material	The material of this block.
piston_reaction	What happens when a piston pushes this.
placement_material	The material this is placed from (e.g. redstone_wire is made from redstone).
requires_tool	Whether this requires a tool to break.
light_emission	How much light this gives off.
clone	A copy of this.

Block

A reference to an actual block in the world.

This inherits all the properties of block states and materials.

Property	Description
is_powered	Whether this has redstone power.
is_passable	Whether a player can walk through this.
x	The x coordinate of this.
y	The y coordinate of this.
z	The z coordinate of this.
entity	The block (tile) entity here, if one exists.
state	The state of this block.

Block Entity

The tile entity attached to a block, e.g. a furnace to a furnace block. Most blocks do not have a block entity. Individual block entity types may provide extra properties.

This inherits all properties from block.

Property	Description
block	The block this entity belongs to.

Command Sender

Something that can send a command, such as a player, entity, command block or the console.

Property	Description
name	The name of this.
has_permission	fn(x) -> Whether this has the permission x.
send_message	fn(x) -> Sends the text x to this.
is_op	Whether this is a server operator.

Player

A player.

Inherits all properties of a command sender.

Property	Description
uuid	The unique ID of this player.
online	Whether this is online.
location	The player's location.
game_mode	The player's game mode.
health	The player's health.
killer	The thing that killed the player.
last_damage	The last amount of damage taken by the player.
yaw	The player's horizontal rotation. Can be set.
pitch	The player's vertical rotation. Can be set.
x	The x coordinate of this.
y	The y coordinate of this.
z	The z coordinate of this.
compass_target	Where the compass points.
can_fly	Whether this can fly.
bed_location	Where the bed of this is.
arrows_in_body	How many arrows are stuck in this.
view_distance	The player's view distance.
has_cooldown	fn(x) -> Whether this has a cooldown for the material x.

Unknown

The unknown kind, that all miscellaneous objects are.

This has no specific properties.