Modding:Bundles

Bundles are mods that contain multiple mod types within them. (Introduced in r56.1)

Methods of bundling

There are two ways to create bundles:

1) Manually through JSON (forced)

2) Automatically through the mod dependencies system

Generally speaking, manual bundles should only be made if the submods have no potential use independently. For instance, before bundling a monster and a map manually, consider that another modder might want to use the monster in a custom map, or spawn it in a procedural map. In that case, having each of the monster and the map individually listed in the mod database allows more flexibility for the mods to be used in future ways.

Mod dependencies bundling (Automatic)

This is the easiest and most flexible way of bundling -- each mod can list its own dependencies in the mod portal. Then when the user installs the mod, all dependencies will be installed recursively.

Manual bundling

Set the type of the mod to BUNDLE.

Syntax

{
	"type": "BUNDLE",
	"includedMods":
	[
		{
			"spawn": true,
			"mod":
			{ ... }
		},
		{
			"spawn": true,
			"mod":
			{ ... }
		}, ...
	]
}

Parameters

includedMods will be an array of sub mods, each one specifies:

• spawn - whether the item or monster should be spawned in the environment
• mod - the submod's json

Full example

This example bundles the vending machine and the soda it dispenses as one combined mod. It only spawns the vending machine, but since the soda is loaded, the vending machine can spawn soda through its lua code.

(In reality, you would not want to bundle these together as by using the automatic dependency system, other mods could make use of the soda entity for their own purposes.)

{
	"type": "BUNDLE",
	"includedMods":
	[
		{
			"spawn": true,
			"mod":
			{
				"type": "ENTITY",
				"name":
				{
					"literalString": "Vending Machine"
				},
				"description":
				{
					"literalString": "The vending machine advertises $1 for one diet soda."
				},
				"doUse":
				{
					"programBoolean": true
				},
				"isUseable":
				{
					"literalBoolean": true
				},
				"lua":  "function doUse()\r\n\t-- NOTE: If creating a full store, it would probably be better to use the\r\n\t-- existing store code, however as of Feb 2018 this is not yet exposed to\r\n\t-- LUA modding.  However, this is fine for a 'shop' that only sells one\r\n\t-- item.\r\n\r\n\tplayer = Player.getInstance();\r\n\r\n\tif player.removeCash(1) then\r\n\t\t-- Player has enough currency to cover the transaction, and it was\r\n\t\t-- deducted successfully.\r\n\r\n\t\t-- This matches the id field in entity json.  Generally best to use the\r\n\t\t-- same name as your mod wiki page to prevent conflicts between multiple\r\n\t\t-- mods.\r\n\t\tsoda = Entity.generate(\"Sample Soda\");\r\n\r\n\t\tif soda == nil then\r\n\t\t\tMainScreen.addGameText(\"Please also load the Sample Soda mod.\");\r\n\t\telse\r\n\t\t\tMainScreen.addGameText('You insert $1 into the vending machine.  ' ..\r\n\t\t\t\t'It spits out a can of diet soda.');\r\n\r\n\t\t\t-- Set location to be the same location as vending machine.\r\n\t\t\t-- Since the player must be next to the vending machine to use it,\r\n\t\t\t-- this function works fine.  Another (longer) method would be to get\r\n\t\t\t-- the vending machine's location and set the soda's location to it.\t\t\t\r\n\t\t\tsoda.moveEntityToSameRoomAsPlayer();\r\n\t\tend\r\n\telse\r\n\t\t-- Player didn't have enough currency to cover the total cost of transaction.\r\n\t\t-- No currency was deducted.\r\n\t\t\r\n\t\tMainScreen.addGameText('You need at least $1 to buy a soda.');\t\r\n\tend\r\n\r\n\treturn true; -- Automatic continue scene\r\nend"
			}
		},
		{
			"spawn": false,
			"mod":
			{
				"type": "ENTITY",
				"id": "Sample Soda",
				"name":
				{
					"literalString": "Soda"
				},
				"description":
				{
					"literalString": "A can of diet soda."
				},
				"doUse":
				{
					"programBoolean": true
				},
				"isUseable":
				{
					"literalBoolean": true
				},
				"isPickupable":
				{
					"literalBoolean": true
				},
				"lua":  "function doUse()\r\n\t-- NOTE: The engine actually has support for food objects that will adjust\r\n\t-- the player's weight appropriately, however, this is not yet exposed to\r\n\t-- LUA modding as of Feb 2018.  For the purposes of this example, the soda\r\n\t-- will just replenish HP with no other consequences.\r\n\r\n\tplayer = Player.getInstance();\r\n\r\n\tMainScreen.addGameText('You gulp down the soda.  ');\t\r\n\r\n\tplayer.heal(3); -- Heal 3HP\r\n\r\n\tthis.deleteEntity(); -- Remove entity from world or inventory\r\n\r\n\treturn true; -- Automatic continue scene\r\nend"
			}
		}
	]
}