This page is up to date as of v3.1.0

Map Scripts

Map scripts are defined by a script.js file and allow you to do incredible things with your map that simple image editing can't.

Scripts give you the power of javascript, similar to mods, to make changes to your map based on events.

At least a basic understanding of Javascript, or the ability to use Google/ChatGPT, is highly recommended

helpers

helpers contains a few helper functions to simplify basic calculations.

lerp

lerp takes 3 parameters: amount, a, and b.

amount must be a number between 0 and 1, and lerp will return a value, based on the percentage amount, between a and b.

CML.scriptAPI.helpers.lerp(0.6, 0, 5); // = 3 (60% between 0 and 5)

map

map takes 5 parameters: number, inMin, inMax, outMin, outMax.

This function maps number (from inMin to inMax) to the new range of outMin to outMax.

e.g. mapping 5, with inMin being 0 and inMax being 10, to the new range of outMin 0, outMax 100 would give 50.

CML.scriptAPI.helpers.map(0.3, 0, 1, 10, 20); // = 13 (30% between 10 and 20)

round

round takes 2 parameters: number and precision

This simply returns the number rounded to the specified precision.

precision should be a power of 10. e.g 10.527 rounded with precision 100 would give 10.53.

CML.scriptAPI.helpers.round(3.14159, 100); // = 3.14

spawnBlock

The spawnBlock method spawns a block such as a launcher or conveyor.

This function takes in an x and y in the form of pixel units and should be aligned to the 4x4 grid to work properly.

The function takes the type as the final argument, which accepts the name of the block in the form of its internal name.

Tip: You can find the stored table by using CML.internals.spawnBlockData.blocks in the console

CML.scriptAPI.spawnBlock(500, 200, "ConveyorLeft"); // Places a conveyor belt at x: 500, y: 200

spawnParticle

The spawnParticle function allows you to spawn particles such as water, gold, sand, etc.

It takes in the x and y of the pixel as well as the type.

Tip: You can find the list of types by using CML.internals.particles in the console

CML.scriptAPI.spawnParticle(500, 200, "Sand"); // Spawns a sand particle at x: 500, y: 200

spawnMovingParticle

The spawnMovingParticle function is very similar to spawnParticle but it spawns the particle with a set velocity.

This function takes in x, y, velX, velY, as well as the type as defined in spawnParticle.

Note that velocity has to be suprisingly high to notice any effect, experiment starting with a velocity of 50 or 100

CML.scriptAPI.spawnMovingParticle(500, 200, 200, -200, "Water"); // Spawns a water particle at x: 500, y: 200 moving right (x: 200) and up (y: -200)

setElement

setElement is the internal function that spawning a particle uses, but it can also be used to set solid elements.

This function takes in the x and y as well as the type of the element.

If you want to spawn solid elements, type is just the name of the element.

Tip: You can find the list of solids by using CML.internals.solids in the console

CML.scriptAPI.setElement(500, 200, "Fluxite"); // Places fluxite at x: 500, y: 200

isPlaceable

isPlaceable simply returns true if a given pixel has no buildings or other particles and can be used if you don't want to override existing elements when spawning anything.

This function just takes in the x and y and returns true/false based on if that pixel is empty or not.

CML.scriptAPI.isPlaceable(500, 200); // Returns true/false based on if this tile is empty (no building or other element blocking it)

revealFog

This function allows you to forcefully start the fog reveal process at a given x and y.

This function takes in only x and y and can be set on ANY fog particle, even fog water or fog lava!

CML.scriptAPI.revealFog(500, 200); // Reveals *any* fog particle at x: 500, y: 200

playCinematic

playCinematic is one of the more advanced scriptAPI features, as it has a somewhat complex data structure.

For simplicity, I will give you a template of the datastructure as used with playCinematic and describe how to expand upon it.

CML.scriptAPI.playCinematic({
	start: {
		x: 100,
		y: 320,
	},
	path: [
		{
			x: 1000,
			y: 320,
			easing: CML.scriptAPI.basicEasing.in_out,
			duration: 8000,
		},
	],
});

This example cinematic moves between the pixel coordinates 100, 320 and 1000, 320. (A horizontal camera pan)

The start determines where the cinematic starts, and it will transition between each point after that. (i.e. Start -> Point1 -> Point2 -> etc)

Each path point has a duration which specifies how long it takes to transition from the previous point to the new point.

The easing function also allows you to write complicated easing behavior, but for simplicity you can check out the basicEasing functions.

If you want more advanced behavior, you can write your own functions such as arrow functions. The only parameter given to easing functions is t which is the percent representing how far into the path it is. (e.g. if duration is 8s then t will be 1 after 8s)

basicEasing

basicEasing is a collection of simple easing functions if you don't want to write your own.

linear

Moves between two points at a set speed

Internal Expression: (t) => t

in_out

Uses quadratic ease in out to transition between two points.

Internal Expression: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;

in_out_custom

Unlike the other easings, this is a function that must be called first before passing the result as an easing function.

This function allows you to change what parts of the transition are ease in or out respectively. (e.g. you can do first 25% ease in, 75% ease out)

This function takes in the percent that easeIn should take, and the rest will be ease out