This page is up to date as of v4.1.3

Map Scripting

In older versions of the map loader, scripts used to be in a script.js file that also had the CML.scriptAPI.

This is now deprecated, since v2 of the modloader (fluxloader) now allows maps to be directly loaded and treated as mods.

This means any map scripting you want to do, can be done the same way a regular mod would do it, with slight tweaks to ensure it only runs on your map.

Getting Started

To script your map, you'll want to start it off similar to a mod. You can have any of the entrypoints, such as electron, game, and worker.

You use these files exactly how you would if you were making a mod, including the fluxloaderAPI, corelib and anything else the mods you choose to depend on expose for you to use.

Map Events

Map Loading/Unloading

To help you know when your map is being loaded, the CML exposes a few events for when a given map is loaded or unloaded.

The unloaded event is only in the electron entrypoint, as the other 2 are reset when changing maps anyway.

The events are appropriately named CML:mapLoaded and CML:mapUnloaded. The only argument given by them is the id of the map (modID)

Example also using corelib:

fluxloaderAPI.events.on("CML:mapLoaded", (map) => {
	if (map === "example-map") {
		corelib.schedules.register("example:rain", 250);
	}
});

fluxloaderAPI.events.on("CML:mapUnloaded", (map) => {
	if (map === "example-map") {
		corelib.schedules.unregister("example:rain");
	}
});

Player Landed

CML exposes the CML:playerLanded event, which is trigged when the landing sequence ends.

fluxloaderAPI.events.on("CML:mapLoaded", (map) => {
	if (map === "example-map") {
		fluxloaderAPI.events.on("CML:playerLanded", () => {
			console.log("Landing Sequence Ended!!");
		});
	}
});

Player Unstuck

CML exposes the CML:playerUnstuck event, which is trigged when the player uses the "Unstuck" button.

fluxloaderAPI.events.on("CML:mapLoaded", (map) => {
	if (map === "example-map") {
		fluxloaderAPI.events.on("CML:playerUnstuck", () => {
			console.log("Player unstuck");
		});
	}
});

Map Patches

Map patches are just standard fluxloaderAPI patches with some extra checks. For these extra checks, you'll have to use the mapLoaded event to verify when to register your patches, and ensure you remove them on the mapUnloaded event.

If your patches are simple (main requirement is that they never change), you can register them using the CML.registerMapPatches() helper.

This helper simply takes in your mapID, and a structure of files and what patches to apply for them. (These patches are directly given to the fluxloaderAPI and must be in the same format)

The helper also handles registering/unregistering your patches, so there's no need to listen to the map load/unload event for these.

Example using a patch from core limiter:

CML.registerMapPatches("example-map", {
	"js/bundle.js": [
		{
			type: "replace",
			from: "navigator.hardwareConcurrency",
			to: config.coreLimit,
			expectedMatches: -1,
		},
	],
});