drwho_tardis-cd2025/API.md

DrWho_Tardis API

This mod has a couple API functions to make life easier for developers of it, and also support other mods adding their own things to it.

Please note:

• The functions use a colon :, not a dot . after drwho_tardis

• We will refer to the player piloting the TARDIS as the pilot.

• These API may change in future updates, especially v1.3.0. After that update, most API should be stable.

drwho_tardis:register_tardis_exterior(def)

Makes it very simple to add another TARDIS exterior, which is also added to the exterior console unit.

Parameters

• def: A table with all possible parameters in it:

  Required:

  • name: The short name for the exterior. It will be inserted into the itemstring as so: drwho_tardis:tardis_<name> and drwho_tardis:tardis_<name>_locked.

  • texture: The texture used for the TARDIS. Defaults to using the "mesh" format, just use one of the existing textures as a base. If you want to use "nodebox" to draw a node's texture on it, set that in drawtype.

  Optional:

  • light: (default: 10): Allows you to make the exterior glow less, more, or not at all (0). Make sure it is a value between 0 and 14.

  • description: (default: "Tardis"): The player-facing title of the actual item. Not recommended to be changed.

  • title: (default: name^): The title of the exterior when listed on the exterior console unit. Defaults to name, but that is usually all lowercase so it is a good idea to set this with a capitalised word.

  • drawtype: (default: "mesh"): As mentioned above, this allows the modder to set the drawtype to "nodebox". Then you can pass a single node texture to texture which will be put all over the TARDIS. This is used in the default Stone, Leaves and Invisible textures.

  • groups: must have tardis = 1 and should also have not_in_creative_inventory = 1 as well. The only Tardis that is in creative inventory is the default one.

Additional notes

• Does not return anything.
• Ensure that the name is unique, otherwise it will override the previous one with that name and break some things.

Example usage

-- Exterior with mesh texture
drwho_tardis:register_tardis_exterior({
	name = "green",
	texture = "tardis_green.png",
	title = "Green",
	author = "Skivling"
})

-- Exterior using existing textures (Nodebox drawtype)
drwho_tardis:register_tardis_exterior({
	name = "stone",
	texture = "default_stone.png",
	drawtype = "nodebox",
	light = 0,
	title = "Stone",
	author = "PiDemon"
})

drwho_tardis:register_in_door_style(def)

Allows you to create custom styles for the Tardis interior doors.

Parameters

• def (table):
  • texture: The texture for the door.
  • description: The player-facing name
  • itemstring: The itemstring of the door

Example usage

drwho_tardis:register_in_door_style({
	texture = "drwho_tardis_inside_door_b.png",
	description = "Tardis Interior Door (style B)",
	itemstring = "drwho_tardis:in_door_b"
})

drwho_tardis:register_sonic_device(def)

Registers a sonic device, whether that be a screwdriver or lipstick (Sarah Jane's, planned). Any item that has the functionality of a sonic.

Parameters

• def is a table with all the parameters in it:

Required:

• gentype: Tell the function if you are setting your own texture (custom), choosing from the 1/3 textures (choose), or making it random (random).

  • If you do the arithmetic for randomising the numbers before giving the values to the function, set it to choose.

• sonictype: Either "screwdriver" or a custom one, such as "lipstick". It will default to "screwdriver" but should be specified.

• no_creative: If true, the new sonic device will not appear in the creative inventory. If false, it will appear in the creative inventory.

  • This can be useful for player-only sonics, or if you are registering lots that don't need to flood the inventory.

Optional:

• texture: If the modder wants to use a custom texture that does not use the sonic screwdriver section textures. If so, a customname and customdescription must be given.

• top: The number for what texture to be used in the top third of a sonic, defaults to random.

• mid: The number for what texture to be used in the middle third of a sonic, defaults to random.

• bottom: The number for what texture to be used in the bottom third of a sonic, defaults to random.

• customname: This is the itemstring. It defaults to "drwho_tardis:sonic_"..sonictype.."_"..top.."_"..mid.."_"..bottom, so if you want it to be part of your mod's modname space, you must use this value, as well as appending the modname with : to tell the engine to not care that the modname isn't drwho_tardis even though it appears to be registered from that because of the function.

  • For example, :extra_sonics:sonic_playing_cards_3 if, for some reason you wanted a pack of cards to have sonic ability. Actually, that doesn't sound like a bad idea...

• tool_capabilities: A table, allowing you to customize the capabilities of that particular sonic. full_punch_interval, groupcaps.sonic allows you to change the uses and maxlevel of it, the higher they are the more durability the sonic has.

• sounds: Must be a table where the value sonic_use is a custom sound file to play when the sonic is used, and includes the max_hear_distance.

Return value

Returns the full item_name.

• It may include the extra : if you put your own modname in the customname, if so you can remove it with item_name = item_name:match"^.-:(.+)".

Additional notes

• A different API may be added in the future that allows custom sonic functions to be added as long as they don't break the default ones.

• The names of each variable in def will most likely change in version 1.3.0 when APIs are cleaned up.

Example usage:

-- Register sonic playing cards as part of the mod 'extra_sonics'
drwho_tardis:register_sonic_device({
    gentype = "custom", -- We are specifying the texture
    texture = "extra_sonics_playing_cards.png",
    sonictype = "playing_cards",
    no_creative = false, -- We want it to appear in the creative inventory
    customname = ":extra_sonics:sonic_playing_cards", -- itemstring
    customdescription = "Sonic Playing Cards", -- player-facing name
})

drwho_tardis.get:tardis_ext_position(player)

Returns the exterior position of a certain player's Tardis.

Return value

Returns success, errmsg, pos

• success is a boolean value if it worked or not

• errmsg is a string which has an error message if success is false.

• pos is the position of the Tardis.

drwho_tardis.get:interior_type(player)

Returns the interior type of a player's Tardis, but returns "old" even if they don't have a Tardis.

Return value

Returns type:

• type is a string which corresponds to the interior type they have. All Tardises made before v1.2.0 are of type "old", the newer interiors have not been made yet but will have other type values.

drwho_tardis.get:interior_depth(player)

Returns the default interior depth that is used in new Tardises. It is an integer, probably -10000 or -50 depending on the gametype.