Game API CmdId

Index: GameAPI

## Note on Game\_Request

The format for Game\_Request consists of three arguments:

First being a reference to the cmdid, a 'Request' (See list below) (For instance CmdId.Request\_Player\_List

Second being the Sequence number, of type ushort (Effectively a smaller int, unsigned int16). This number is described in detail below, but can be any arbitrary number, that you can use to 'look for callbacks relating to your call'

Third being of type 'data': Ambique format, that expects the requests parameters, in the format of a

new Eleon.Modding.<>(value)

<> being a reference to a valid class, valid being valid under this.

(for instance: GameAPI.Game\_Request(CmdId.Request\_Playfield\_Entity\_List, (ushort)19983, new Eleon.Modding.PString('Eleen')); , would request a callback for entity\_list, with ID 19983, for a name (string) specified by 'Eleen'. Note that most expects .id, some .PString, and others have their own class (PlayerInfo for instance)

## Note on Sequence Numbers

The second argument to the Game\_Request and Game\_Event methods, is the, "Sequence Number" for the request. When submitting a request, the sequence number provided will be used to identify the response message. So:

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_List, (ushort)1, null);

```

will result in a call to Game\_Event with the arguments:

**Sample:**

```
(CmdId.Event_Player_List, 1, <Some PlayerIdList>);

```

ushort gives us a keyspace of 65,535, which means you should feel free to use random sequence numbers, but make sure to validate that the resonse you're receiving is of the correct type.

Also note that any game-generated events are presented with a sequence number of 0, so you shouldn't use it to track requests.

#### Concept: Sequencenumbers & current flaws

The idea behind sequence numbers, is that you can keep an internal 'log' of what you have sent, together with a dumb of data, that you can use when you receive it again.

However, the current API format sends the responses to all mods installed, so using it as a 'ticketing system' MAY be unreliable.

If you use fixed numbers, you should claim an interval below 15.000.

You should atleast start at 15.000+, if you use it for a ticketing system. This should still leave you with plenty of numbers. Keep in mind however, that it might still conflict with some mods:

*Please attempt to place your mod properly, relative to the numbers you use (so 10 is before 20, 30 before 500, etc)*

#### Known mods using fixed-sequence numbers, and their intervals

If you do not use flexible tickets, due to the potential for conflicts, please add your mod, and the sequence number interval you use, below:

* CommandCrate: 9980-9989 (Currently in use: 9984-9989)

* SpotGuard: 9990-9999 (Currently in use: 9995-9999)

*Please try to limit the claimed space to the least you need. 10 is a reasonable* *amount for complex mods, while fewer can easily be used with more straightforward mods.*

*It is reasonable to claim an amount, slightly over what you actually need, to leave room for future expansion. Please do try not to overclaim tho.*

#### Known mods using non-fixed sequence numbers, and which intervals they use for tickets

If you do not use fixed tickets, please add your mod below. This will help to identify potentially weird behaviour, with multiple mods.Please also note which interval your tickets run from-to.

* "Xango's mods" () : All my mods check all 3 pieces of data received to ensure that what is received is what was asked for, done this say SeqNr does not matter. Xango's SeqNr Solution

**Mods that does neither, and both:**

* LostInPlaces' EmpyrionAdminTools : Uses a pattern-approach, to generate sequence-requests. Method is explained here

## Help finding what you are seeking

The following section consists of two headings:

**Requests** and **Events**

A **Request** is when you 'know what you want to know about':

For instance, if you have a playfield name (Example: 'Eleen' is the playfield (Knowing it is a Eleon.Modding.PString is specified from the entry 'Param data' from below)), and want information on all the entities currently residing on said playfield, you could in your code write:

```
GameAPI.Game_Request(CmdId.Request_Playfield_Entity_List, (ushort)1, new Eleon.Modding.PString("Eleen"));

```

This will make the game return you an **Event,** containing the requested data (see below, the entry 'Corresponding event' is what would be returned.

Requests can also be without a returning event, in the instance where you are **Changing** something, such as 'Request\_Player\_AddCredits'.

(These requests technically does return an **Event\_Ok** or an **Event\_Error**, if you want to make sure they were successfull or not. But this is implicit in the list below)

An **Event** is getting data, either requested, or just 'because it happened ingame'.

An Event will contain different types of data. The entry 'Param data' (Under the event itself**!**), determines which kind you will be returned.

(You are usually interested in parsing this into an object you can work with, for instance by)

```
PdaStateInfo Pad = (PdaStateInfo)data;

```

Note that the **Event** will always be returned in the **Game\_Event** function, and can be accessed by either its CmdId (event-name), and/or sequence number (shortInt). See above sections, for more on these.

You can actively send a request. The request may contain some data, that you may need to specify, depending on the request (See '**Param data:**' for what is expected/possible)

Once sent, it may trigger an event (See '**Corresponding** **event**' for which. If not specified will return nothing, or simple the '**Event\_Ok**' or the '**Event\_Error**'.

Events may be triggered without having to be a response to a request, if something happens in the game, that warrants that event being triggered.

The event will return code in format specified in '**Param data:**'. Note, that it will be a 'dummy object' (typeless), that you have to convert.

This should simply be done by

```
 GlobalStructureList gi = (GlobalStructureList)data

```

(Example, if the data is expected to be of type 'GlobalStructureList' based on the 'param data' specifying this is the type. (the event **Event\_GlobalStructure\_List** for example)

You can from the '**Param data:**', see what data is possible to extract from here.

Finding which are right for your case, is usually easiest by trying several *Keyword-searches* on the list below, such as for 'PDA', 'Playfield' (...), via browsers ctrl+f (keybinding varies)

## Requests

### Request\_Player\_List

**Description:** Retrieves a listing of all online players.

**Param data:** nothing.

**Corresponding** **event:** Event\_Player\_List

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_List, someNonZeroKey, null);

```

### Request\_Player\_Info

**Description:** Retrieves player information. The ID used as a parameter is the entity id, not the Steam id.

**Param data:** Id

**Corresponding** **event:** Event\_Player\_Info

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_Info, someNonZeroKey, new Eleon.Modding.Id(12345));

```

12345 being the player's entity ID

### Request\_Player\_SetPlayerInfo

**Description:** Set basic information of the player. This is to modify the player's starting playfield, health, stamina, food, oxygen and experience points and so on.

**Param data:** PlayerInfoSet

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_SetPlayerInfo, someNonZeroKey, new PlayerInfoSet()
{
    entityId = 28,
    oxygenMax = +1000,
    health = +500,
    food = +500,
});

```

**Note:** use oxygenMax for oxygen

### Request\_Player\_GetInventory

**Description:** Retrieves players inventory. The ID used as a parameter is the entity id, not the Steam id.

**Param data:** Id

**Corresponding** **event:** Event\_Player\_Inventory

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_GetInventory, someNonZeroKey, new Eleon.Modding.Id(12345));

```

### Request\_Player\_SetInventory

**Description:** Sets players inventory. Refer to Param data for what is passed.

**Param data:** Inventory

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_SetInventory, someNonZeroKey, new Eleon.Modding.Inventory()
{
    playerId = 12345,
    toolbelt = Toolbelt,
    bag = Bag
}
);

```

### Request\_Player\_AddItem

**Description:** Adds an item to the player's inventory. Refer to Param data for what is passed.

**Param data:** ItemStack

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_AddItem, someNonZeroKey, new IdItemStack()
{
id = 28,
itemStack = { id = 490, count = 1, slotIdx = 0, ammo = 0, decay = 0 }
});

```

### Request\_Player\_ItemExchange

**Description:** Sends an inventory to the player (can be empty) which will be shown in a storage-window that opens for the player. The player can take items out of this window or put items into it. After closing the window the items left in that window will be send back as an event.

**Param data:** ItemExchangeInfo. int id, string title, string description, string buttonText, ItemStack[] items

**Corresponding** **event:** Event\_Player\_ItemExchange

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Player_ItemExchange, someNonZeroKey, new ItemExchangeInfo(playerId, "Gimme Stuff", "Because I said so!", "Here Ya Go", ExchangeItems));

```

### Request\_Player\_GetAndRemoveInventory

**Description:** Removes the players inventory and sends all items back that were successfully removed. Items that were droped by the player are not send back, to prevent exploiting this function.

**Param data:** Id

**Corresponding** **event:** Event\_Player\_GetAndRemoveInventory

**Sample:**

### Request\_Player\_Credits

**Description:** Requests the current credits of the player

**Param data:** Id

**Corresponding** **event:** Event\_Player\_Credits

**Sample:**

### Request\_Player\_SetCredits

**Description:** Sets the player credits

**Param data:** IdCredits

**Sample:**

### Request\_Player\_AddCredits

**Description:** Adds credits to the player (+/-)

**Param data:** IdCredits

**Sample:**

### Request\_Player\_ChangePlayerfield

**Description:** Warps or moves a player. You can change playfield, position and rotation

**Param data:** IdPlayfieldPositionRotation

**Sample:**

**Note:** NOTE! Player MUST BE on a different playfield, than the target, in order to use this request!

### Request\_Blueprint\_Finish

**Description:** Finish a started blueprint for the player

**Param data:** Id

**Sample:**

GameAPI.Game\_Request(CmdId.Request\_Blueprint\_Finish,someNonZeroKey, new Id(playerId));

### Request\_Blueprint\_Resources

**Description:** Adds or replaces the blueprint ressourses of the player

**Param data:** BlueprintResources

**Sample:**

### Request\_NewEntityId

**Description:** Request a new entity Id to spawn a new structure

**Param data:** nothing.

**Corresponding** **event:** Event\_NewEntityId

**Sample:**

### Request\_Entity\_Teleport

**Description:** Teleports a player or structure on the same playfield (only position and rotation, no playfield change)

**Param data:** IdPositionRotation

**Sample:**

### Request\_Entity\_ChangePlayfield

**Description:** Warps or moves a structure. You can change playfield, position and rotation.

Note: If you want to teleport a player you have to use "Request\_Player\_ChangePlayerfield"

**Param data:** IdPlayfieldPositionRotation

**Sample:**

### Request\_Entity\_Destroy

**Description:** Destroys the structure.

**Param data:** Id

**Sample:**

### Request\_Entity\_Destroy2

**Description:** Destroys an entity.

**Param data:** IdPlayfield.

**Sample:**

### Request\_Entity\_PosAndRot

**Description:** Requests the current position and rotation of a player or structure.

**Param data:** Id

**Corresponding** **event:** Event\_Entity\_PosAndRot

**Sample:**

### Request\_Entity\_SetName

**Description:** Requests to set the name of an entity. (Only structure?)

**Param data:** IdPlayfieldName

**Corresponding** **event:** Nothing.

**Sample:**

### Request\_Entity\_Spawn

**Description:** Spawns a new structure. First you have to retrieve a new entity Id for the structure. The prefabName property in EntitySpawnInfo needs to fit to the selected structure.

note: prefabName is the name of the epb file, for instance

BA\_CivilFarm.epb is a blueprint in the default prefabs folder. it has a Group Name "CivilSettlement", and a Blueprint Spawn Name, "Farm"

you would spawn it with the prefabName: BA\_CivilFarm

**Param data:** EntitySpawnInfo

**Related commands:** Request\_NewEntityId, Event\_NewEntityId

**Sample:**

### Request\_Playfield\_List

**Description:** Requests all loaded playfields.

**Param data:** nothing.

**Corresponding** **event:** Event\_Playfield\_List

**Sample:**

### Request\_Playfield\_Stats

**Description:** Requests statistics of the playfield (has to be loaded).

**Param data:** PString

**Corresponding** **event:** Event\_Playfield\_Stats

**Sample:**

### Request\_Load\_Playfield

**Description:** Requests to load a playfield for a few seconds to be able to send some commands.

**Param data:** PlayfieldLoad

**Corresponding** **event:** Event\_Playfield\_Loaded

**Sample:**

### Request\_Dedi\_Stats

**Description:** Requests statistics of the current game.

**Param data:** nothing.

**Corresponding** **event:** Event\_Dedi\_Stats

**Sample:**

### Request\_GlobalStructure\_List

**Description:** Requests all structures and their infos in game per playfield. This includes unloaded playfields.

**Param data:** nothing.

**Corresponding** **event:** Event\_GlobalStructure\_List

**Sample:**

### Request\_GlobalStructure\_Update

**Description:** Requests all structures of the playfield (has to be loaded).

**Param data:** PString

**Corresponding** **event:** Event\_GlobalStructure\_List

**Sample:**

### Request\_Structure\_Touch

**Description:** Requests to touch that structure to reset the DecayTime.

**Param data:** Id

**Sample:**

### Request\_Structure\_BlockStatistics

**Description:** Requests block information of that structure.

**Param data:** Id

**Corresponding** **event:** Event\_Structure\_BlockStatistics

**Sample:**

### Request\_Get\_Factions

**Description:** Requests all factions from a certain Id onwards. If you want all factions use Id 1.

**Param data:** Id

**Corresponding** **event:** Event\_Get\_Factions

**Sample:**

### Request\_InGameMessage\_SinglePlayer

**Description:** Sends a message to a player that is shown on the top right of the Hud. A priority can be assigned to highlight the message and alert the player through a sound effect (Like drone messages).

**Param data:** IdMsgPrio

**Sample:**

### Request\_InGameMessage\_Faction

**Description:** Sends a message to a faction that is shown on the top right of the Hud. A priority can be assigned to highlight the message and alert the faction through a sound effect (Like drone messages).

**Param data:** IdMsgPrio

**Sample:**

### Request\_InGameMessage\_AllPlayers

**Description:** Sends a message to all player that is shown on the top right of the Hud. A priority can be assigned to highlight the message and alert the players through a sound effect (Like drone messages).

**Param data:** IdMsgPrio

**Sample:**

### Request\_ShowDialog\_SinglePlayer

**Description:** Sends a message to a player that will be shown as a message box with **up to** 2 buttons which you can set yourself.

**Param data:** DialogBoxData

**Corresponding** **event:** Event\_DialogButtonIndex

**Sample:**

For Colors: color [c][hexid][-][/c] [c][019245]test[-][/c]

```
GameAPI.Game_Request(CmdId.Request_ShowDialog_SinglePlayer, someNonZeroKey, new DialogBoxData()
{
    Id = 15445,
    MsgText = "Do you like programming API Mods for Empyrion?",
    PosButtonText = "I Guess so",
    NegButtonText = "Certainly Not"
});

```

### Request\_AlliancesAll

**Description:** Requests all alliance differences (to default).

**Param data:** nothing.

**Corresponding** **event:** Event\_AlliancesAll

**Sample:**

```
private async Task<bool> AreAllies(int factionId, int testFactionId)
{
   if (factionId == testFactionId) return true;

   var allFactions = (await Request_Get_Factions(new Id(0))).factions;
   var f1 = allFactions.FirstOrDefault(F => F.factionId == factionId);
   var f2 = allFactions.FirstOrDefault(F => F.factionId == testFactionId);

   var allied = f1.origin == f2.origin;  // default allied

   var allies = await Request_AlliancesAll();
   var allyTest1 = f1.factionId << 16 | f2.factionId;
   var allyTest2 = f2.factionId << 16 | f1.factionId;

   if (allies.alliances != null && (allies.alliances.Contains(allyTest1) || allies.alliances.Contains(allyTest2))) allied = !allied; // default changed

   log($"AreAlliesResult:{allied}\n" +
       $"Routefaction:{factionId}/{GetName(allFactions, factionId)} Origin:{f1.origin} Playerfaction:{testFactionId}/{GetName(allFactions, testFactionId)} Origin:{f2.origin}" +
       allies.alliances?.Aggregate($"\nFactions:#{allFactions.Count} AlliesChange:#{allies.alliances.Count}", (S, A) => S + $"\nChangeallied:{A >> 16}/{GetName(allFactions, A >> 16)} <=> {A & 0x0000ffff}/{GetName(allFactions, A & 0x0000ffff)}"),
       LogLevel.Message);

   return allied;
}

```

### Request\_AlliancesFaction

**Description:** Set the alliance differences (to default) of that faction.

**Param data:** AlliancesFaction

**Corresponding** **event:** Event\_AlliancesFaction

**Sample:**

### Request\_ConsoleCommand

**Description:** Requests to execute a command that also can be send over telnet.

**Param data:** PString

**Sample:**

```
String command = "SAY '" + msg + "'";
GameAPI.Game_Request(CmdId.Request_ConsoleCommand, (ushort)CmdId.Request_InGameMessage_AllPlayers, new Eleon.Modding.PString(command));

```

**Data-Reference:** Console\_Commands , Telnet\_Commands

### Request\_GetBannedPlayers

**Description:** Requests all banned player information.

**Param data:** nothing.

**Corresponding** **event:** Event\_BannedPlayers

**Sample:**

### Request\_Playfield\_Entity\_List

**Description:** Requests all entities on a playfield.

**Param data:** IdPlayfield. [PString]

**Corresponding** **event:** Event\_Playfield\_Entity\_List

**Sample:**

```
GameAPI.Game_Request(CmdId.Request_Playfield_Entity_List, (ushort)19983, new Eleon.Modding.PString("Eleen"));

```

## Events

### Event\_ConsoleCommand

**Description:** Event Triggered when a consoleCommand is entered (ingame - Things sent through requestconsolecommand doesn't trigger it).

**Param data:** ConsoleCommandInfo

### Event\_Player\_Connected

**Description:** Event Triggered when a player connects.

**Param data:** Id

### Event\_Player\_Disconnected

**Description:** Event Triggered when a player disconnects.

**Param data:** Id

### Event\_Player\_List

**Description:** Lists all online player Id's.

**Answer to Request:** Request\_Player\_List.

**Param data:** IdList

### Event\_Player\_Info

**Description:** Returns all information about the player (Name, Playfield, Faction, Inventory, Credits, Health, ...).

**Answer to Request:** Request\_Player\_Info.

**Param data:** PlayerInfo

### Event\_Player\_Inventory

**Description:** Returns the inventory of the player.

**Answer to Request:** Request\_Player\_GetInventory.

**Param data:** Inventory

### Event\_Player\_ItemExchange

**Description:** Returns the items that the player left in the Item-Exchange window.

**Answer to Request:** Request\_Player\_ItemExchange.

**Param data:** ItemExchangeInfo

### Event\_Player\_Credits

**Description:** Returns the player credits.

**Answer to Request:** Request\_Player\_Credits.

**Param data:** IdCredits

### Event\_Player\_ChangedPlayfield

**Description:** Triggered when a player changes a playfield.

**Param data:** IdPlayfield

### Event\_Playfield\_List

**Description:** Returns all playfields that are currently loaded.

**Answer to Request:** Request\_Playfield\_List.

**Param data:** PlayfieldList

### Event\_Playfield\_Stats

**Description:** Returns current statistics about a playfield

**Answer to Request:** Request\_Playfield\_Stats.

**Param data:** PlayfieldStats

### Event\_Playfield\_Loaded

**Description:** Triggered when a playfield is loaded.

**Param data:** PlayfieldLoad

### Event\_Playfield\_Unloaded

**Description:** Triggered when a playfield is unloaded.

**Param data:** PlayfieldLoad

### Event\_Dedi\_Stats

**Description:** Returns current statistics about the game

**Answer to Request:** Request\_Dedi\_Stats.

**Param data:** DediStats

### Event\_GameEvent

**Description:** Triggers on a PDA event

**Answer to Request:** N/A

**Param data:** GameEventData

**Notes:** Possibly broken as of A7.6.1 : No matter what happens in the pda, nothing gets sent to this.

### Event\_GlobalStructure\_List

**Description:** Returns all structures and their information per playfield. Depending on the request it sends the information for all playfields (Request\_GlobalStructure\_List) or only loaded and selected playfields (Request\_GlobalStructure\_Update).

**Answer to Request:** Request\_GlobalStructure\_List and Request\_GlobalStructure\_Update.

**Param data:** GlobalStructureList

### Event\_Entity\_PosAndRot

**Description:** Returns the player coordinates and rotation.

**Answer to Request:** Request\_Entity\_PosAndRot.

**Param data:** IdPositionRotation

### Event\_Faction\_Changed

**Description:** Triggered when a structure changes its faction.

**Param data:** FactionChangeInfo

### Event\_Get\_Factions

**Description:** Returns faction information.

**Answer to Request:** Request\_Get\_Factions.

**Param data:** FactionInfoList

### Event\_Statistics

**Description:** Triggered in different situations. For example on death of a player, on turn on/off of structure, on removing or adding a core.

**Param data:** StatisticsParam

Details about the usage of the paramdata are found in the ModInterface.cs in the example project.

### Event\_NewEntityId

**Description:** Returns a new unused entity Id which could be used to spawn a new structure.

**Answer to Request:** Request\_NewEntityId.

**Param data:** Id

### Event\_Ok

**Description:** Answer to every request that does not send a event as an answer. If send, the request was successfully executed.

**Param data:** nothing

### Event\_Error

**Description:** If a request could not be executed, an error event will be send. The ErrorInfo contains a ErrorType which is descripte in the ModInterface.cs in the example project.

**Param data:** ErrorInfo

### Event\_Player\_DisconnectedWaiting

**Description:** Triggered when a player has problems to login to the server.

**Param data:** Id

### Event\_ChatMessage

**Description:** Triggered when a player writes a chat.

**Param data:** ChatInfo

### Event\_Structure\_BlockStatistics

**Description:** Returns all blocks of a structure.

**Answer to Request:** Request\_Structure\_BlockStatistics.

**Param data:** IdStructureBlockInfo

### Event\_AlliancesAll

**Description:** Returns all alliances (the differences). See example project on how to get the information.

**Answer to Request:** Request\_AlliancesAll.

**Param data:** AlliancesTable

### Event\_AlliancesFaction

**Description:** Returns all alliances (the differences) for that faction. See example project on how to get the information.

**Answer to Request:** Request\_AlliancesFaction.

**Param data:** AlliancesFaction

### Event\_BannedPlayers

**Description:** Returns all banned players.

**Answer to Request:** Request\_GetBannedPlayers.

**Param data:** BannedPlayerData

### Event\_TraderNPCItemSold

**Description:** Triggered when a player buys something from a NPC-Trader

**Param data:** TraderNPCItemSoldInfo

### Event\_Player\_GetAndRemoveInventory

**Description:** Returns the current inventory that was removed from the player (only items that the game could remove. Items that the player dropped are not listed)

**Answer to Request:** Request\_Player\_GetAndRemoveInventory.

**Param data:** Inventory

### Event\_PdaStateChange

**Description:** PDA chapter activated/deactivated/completed

**Answer to Request:** N/A

**Param data:** PdaStateInfo

### Event\_Playfield\_Entity\_List

**Description:** Returns all entitys of a playfield.

**Answer to Request:** Request\_Playfield\_Entity\_List

**Param data:** PlayfieldEntityList

### Event\_DialogButtonIndex

**Description:** Returns the state of the clicked button

**Answer to Request:** Request\_ShowDialog\_SinglePlayer

**Param data:** IdAndIntValue