Remote Interface

This mod provides a remote interface for modders to access its functionalities for making mod testing to be much easier than before. Modders can also use it to control the behaviors of certain cheats when applied on items or entities on their mods.

Dependency

Before accessing the events and functions in the remote interface, you will have to make sure Creative Mode is loaded before your mod by adding dependency to it in info.json. Optional dependency is recommended so that users of your mod can choose whether they want Creative Mode or not:

"dependencies": ["? creative-mode >= 0.2.3"]

According to the events and functions you need, the required version of Creative Mode may be different. It is recommended to keep it the most updated version.

Interface

The name of interface is creative-mode, so, for example, to use its functions, you use:

remote.call("creative-mode", ...)

In addition, you can also use the following snippet to check whether Creative Mode has been installed correctly:

if remote.interfaces["creative-mode"] then
    -- It is safe to use its events and functions.
end

Events

Events are used to notify your mods that something in Creative Mode has happened. Your mod can register a callback for a given event by using the combination of LuaBootstrap::on_event and LuaRemote::call, where the later function returns the ID of the desired event and the former one registers your callback for the event. See the following examples for details.

`on_enabled`

This event is called when Creative Mode is enabled.

Contains

name :: uint: The event ID.
tick :: uint: Tick the event was generated.
player_index :: uint: Index of the player who enabled Creative Mode.
mod :: string: ID of this mod, which is "creative-mode".

Example

Prints "Creative Mode enabled!" to console when Creative Mode is enabled:

script.on_event(remote.call("creative-mode", "on_enabled"), function(event)
    game.print("Creative Mode enabled!")
end)

`on_disabled`

This event is called when Creative Mode is disabled.

Contains

name :: uint: The event ID.
tick :: uint: Tick the event was generated.
player_index :: uint: Index of the player who disabled Creative Mode.
mod :: string: ID of this mod, which is "creative-mode".

Example

Prints "Creative Mode disabled!" to console when Creative Mode is disabled:

script.on_event(remote.call("creative-mode", "on_disabled"), function(event)
    game.print("Creative Mode disabled!")
end)

Functions

Functions can be used to access the current status of Creative Mode as well as access the other functionalities like cheats and modding UI. There are more functions other than the following list, but those unlisted ones are not designed to be used by modders. They are designed to be used as commands or for examples.

`is_enabled() → boolean`

Checks whether Creative Mode has been enabled.

Return value

true if Creative Mode has been enabled.

Example

Checks if Creative Mode has been enabled before doing something:

if remote.call("creative-mode", "is_enabled") then
    -- Creative Mode has been enabled.
end

`register_remote_function_to_modding_ui(interface_name, function_name, additional_data)`

Registers the function in your remote interface to make it callable via the modding UI as the form of a button. You can provide additional data with the third optional table parameter. So far, only caption and tooltip are supported. This function can be used for updating the additional data as well.

Parameters

interface_name :: string: Name of your remote interface.
function_name :: string: Name of your remote function to be registered.
additional_data :: table (optional): It can contain the following data:
- caption :: string or LocalisedString(optional): Caption of the button representing the function.
- tooltip :: string or LocalisedString (optional): Tooltip of the button representing the function.

Example

Registers the function foo in the remote interface my-interface and represents it by a button whose caption is "Foooo":

remote.call("creative-mode", "register_remote_function_to_modding_ui",
    "my-interface", --  Interface name
    "foo", -- Function name
    {caption = "Foooo"} -- Additional data
)

`deregister_remote_function_from_modding_ui(interface_name, function_name) → boolean`

Deregisters the function in your remote interface to make it uncallable via the modding UI as the form of a button.

Parameters

interface_name :: string: Name of your remote interface.
function_name :: string: Name of your remote function to be deregistered.

Return value

true if such function has been registered before so it can now be deregistered.

Example

Deregisters the function foo in the remote function my-interface. Prints "Good bye foo" if it is successfully deregistered:

if remote.call("creative-mode", "deregister_remote_function_from_modding_ui",
    "my-interface", "foo") then
    game.print("Good bye foo")
end

`has_registered_remote_function_to_modding_ui(interface_name, function_name) → boolean`

Checks whether the given function has been registered so that it is callable via the modding UI as the form of a button.

Parameters

interface_name :: string: Name of your remote interface.
function_name :: string: Name of your remote function to be checked.

Return value

true if such function has been registered.

Example

Do something if the function foo in the remote function my-interface has been registered:

if remote.call("creative-mode", "has_registered_remote_function_to_modding_ui",
    "my-interface", "foo") then
    -- The function has been registered.
end

`exclude_from_keep_last_item(item_name)`

Registers the given item name to the blacklist of the keep last item personal cheat, so the cheat will not apply to such item when it is used by a player, i.e. the cheat will auto refill the item for players.

Parameters

item_name :: string: name of the item to be registered.

Note

This function is used on the alien attractors internally.

Example

Excludes the Assembling Machine 2 from the cheat:

remote.call("creative-mode", "exclude_from_keep_last_item", "assembling-machine-2")

`add_back_to_keep_last_item(item_name) → boolean`

Deregisters the given item name from the blacklist of the keep last item personal cheat, so the item will be affected by it again.

Parameters

item_name :: string: name of the item to be deregistered.

Return value

true if such item has been registered before so it can now be deregistered.

Example

Adds back the Assembling Machine 2 to the cheat:

remote.call("creative-mode", "add_back_to_keep_last_item", "assembling-machine-2")

`has_excluded_from_keep_last_item(item_name) → boolean`

Checks whether the given item name has been ignored by the keep last item personal cheat.

Parameters

item_name :: string: name of the item to be checked.

Return value

true if such item has been registered.

Example

Do something if the Assembling Machine 2 has been blacklisted:

if remote.call("creative-mode", "has_excluded_from_keep_last_item",
    "assembling-machine-2") then
    -- Assembling Machine 2 has been blacklisted.
end

`exclude_from_instant_blueprint(entity_name)`

Registers the given entity name to the blacklist of the instant blueprint personal cheat, so the cheat will not apply on such entity when its ghost is placed by a player.

Parameters

entity_name:: string: name of the entity to be registered.

Example

Exclude the Assembling Machine 3 from the cheat:

remote.call("creative-mode", "exclude_from_instant_blueprint", "assembling-machine-3")

`add_back_to_instant_blueprint(entity_name) → boolean`

Deregisters the given entity name from the blacklist of the instant blueprint personal cheat, so the cheat will apply again on such entity when its ghost is placed by a player.

Parameters

entity_name:: string: name of the entity to be deregistered.

Return value

true if such entity has been registered before, so that it can be deregistered now.

Example

Add back the Assembling Machine 3 to the cheat:

remote.call("creative-mode", "add_back_to_instant_blueprint", "assembling-machine-3")

`has_excluded_from_instant_blueprint(entity_name) → boolean`

Checks whether the given entity name has been excluded from the instant blueprint personal cheat.

Parameters

entity_name:: string: name of the entity to be checked.

Return value

true if such entity has been excluded.

Example

Do something if the Assembling Machine 3 has been excluded:

if remote.call("creative-mode", "has_excluded_from_instant_blueprint",
    "assembling-machine-3") then
    -- Assembling Machine 3 has been excluded.
end

`exclude_from_instant_deconstruction(entity_name)`

Registers the given entity name to the blacklist of the instant deconstruction personal cheat, so the cheat will not apply on such entity when it is marked for deconstruction.

Parameters

entity_name:: string: name of the entity to be registered.

Example

Exclude the Assembling Machine 3 from the cheat:

remote.call("creative-mode", "exclude_from_instant_deconstruction", "assembling-machine-3")

`add_back_to_instant_deconstruction(entity_name) → boolean`

Deregisters the given entity name from the blacklist of the instant deconstruction personal cheat, so the cheat will apply again on such entity when it is marked for deconstruction.

Parameters

entity_name:: string: name of the entity to be deregistered.

Return value

true if such entity has been registered before, so that it can be deregistered now.

Example

Add back the Assembling Machine 3 to the cheat:

remote.call("creative-mode", "add_back_to_instant_deconstruction", "assembling-machine-3")

`has_excluded_from_instant_deconstruction(entity_name) → boolean`

Checks whether the given entity name has been excluded from the instant deconstruction personal cheat.

Parameters

entity_name:: string: name of the entity to be checked.

Return value

true if such entity has been excluded.

Example

Do something if the Assembling Machine 3 has been excluded:

if remote.call("creative-mode", "has_excluded_from_instant_deconstruction",
    "assembling-machine-3") then
    -- Assembling Machine 3 has been excluded.
end

History

Version
0.2.7	All events raised from this mod now contains an additional string parameter "mod" with the value "creative-mode", which is the ID of this mod, including `on_enabled` and `on_disabled`.
	Introduced the `exclude_from_instant_blueprint` function.
	Introduced the `add_back_to_instant_blueprint` function.
	Introduced the `has_excluded_from_instant_blueprint` function.
	Introduced the `exclude_from_instant_deconstruction` function.
	Introduced the `add_back_to_instant_deconstruction` function.
	Introduced the `has_excluded_from_instant_deconstruction` function.
0.2.0	Added player index, tick and event name as the parameters of the `on_enabled` and `on_disabled` events.
	Introduced the `register_remote_function_to_modding_ui` function.
	Introduced the `deregister_remote_function_from_modding_ui` function.
	Introduced the `has_registered_remote_function_to_modding_ui` function
	Introduced the `exclude_from_keep_last_item` function.
	Introduced the `add_back_to_keep_last_item` function.
	Introduced the `has_excluded_from_keep_last_item` function.
0.1.5	Introduced the `is_enabled` function
0.0.3	Introduced the `on_disabled` event.
0.0.3	Removed the parameter in the `on_enabled` event.
0.0.1	Introduced the `on_enabled` event.