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`

**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`

**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`

**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)`

**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`

**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`

**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)`

**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`

**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`

**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)`

**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`

**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`

**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)`

**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`

**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`

**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

```