Game API CmdId

From Empyrion: Galactic Survival Wiki
Jump to: navigation, search

Index: GameAPI

Contents

Note on Game_Request[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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" () : 15.000-65.000 (Currently 500-65.000 for most mods) : (Check on return, if playerID is as expected)

Mods that does neither, and both:

Help finding what you are seeking[edit | edit source]

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[edit | edit source]

Request_Player_List[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Description: Requests the current credits of the player

Param data: Id

Corresponding event: Event_Player_Credits

Sample:

Request_Player_SetCredits[edit | edit source]

Description: Sets the player credits

Param data: IdCredits

Sample:

Request_Player_AddCredits[edit | edit source]

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

Param data: IdCredits

Sample:

Request_Player_ChangePlayerfield[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Description: Adds or replaces the blueprint ressourses of the player

Param data: BlueprintResources

Sample:

Request_NewEntityId[edit | edit source]

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

Param data: nothing.

Corresponding event: Event_NewEntityId

Sample:

Request_Entity_Teleport[edit | edit source]

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

Param data: IdPositionRotation

Sample:

Request_Entity_ChangePlayfield[edit | edit source]

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[edit | edit source]

Description: Destroys the structure.

Param data: Id

Sample:

Request_Entity_Destroy2[edit | edit source]

Description: Destroys a entity.

Param data: IdPlayfield.

Sample:

Request_Entity_PosAndRot[edit | edit source]

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

Param data: Id

Corresponding event: Event_Entity_PosAndRot

Sample:

Request_Entity_SetName[edit | edit source]

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

Param data: IdPlayfieldName

Corresponding event: Nothing.

Sample:

Request_Entity_Spawn[edit | edit source]

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[edit | edit source]

Description: Requests all loaded playfields.

Param data: nothing.

Corresponding event: Event_Playfield_List

Sample:

Request_Playfield_Stats[edit | edit source]

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

Param data: PString

Corresponding event: Event_Playfield_Stats

Sample:

Request_Load_Playfield[edit | edit source]

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[edit | edit source]

Description: Requests statistics of the current game.

Param data: nothing.

Corresponding event: Event_Dedi_Stats

Sample:

Request_GlobalStructure_List[edit | edit source]

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[edit | edit source]

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

Param data: PString

Corresponding event: Event_GlobalStructure_List

Sample:

Request_Structure_Touch[edit | edit source]

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

Param data: Id

Sample:

Request_Structure_BlockStatistics[edit | edit source]

Description: Requests block information of that structure.

Param data: Id

Corresponding event: Event_Structure_BlockStatistics

Sample:

Request_Get_Factions[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

Param data: AlliancesFaction

Corresponding event: Event_AlliancesFaction

Sample:

Request_ConsoleCommand[edit | edit source]

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[edit | edit source]

Description: Requests all banned player information.

Param data: nothing.

Corresponding event: Event_BannedPlayers

Sample:

Request_Playfield_Entity_List[edit | edit source]

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[edit | edit source]

Event_ConsoleCommand[edit | edit source]

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

Param data: ConsoleCommandInfo

Event_Player_Connected[edit | edit source]

Description: Event Triggered when a player connects.

Param data: Id

Event_Player_Disconnected[edit | edit source]

Description: Event Triggered when a player disconnects.

Param data: Id

Event_Player_List[edit | edit source]

Description: Lists all online player Id's.

Answer to Request: Request_Player_List.

Param data: IdList

Event_Player_Info[edit | edit source]

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[edit | edit source]

Description: Returns the inventory of the player.

Answer to Request: Request_Player_GetInventory.

Param data: Inventory

Event_Player_ItemExchange[edit | edit source]

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[edit | edit source]

Description: Returns the player credits.

Answer to Request: Request_Player_Credits.

Param data: IdCredits

Event_Player_ChangedPlayfield[edit | edit source]

Description: Triggered when a player changes a playfield.

Param data: IdPlayfield

Event_Playfield_List[edit | edit source]

Description: Returns all playfields that are currently loaded.

Answer to Request: Request_Playfield_List.

Param data: PlayfieldList

Event_Playfield_Stats[edit | edit source]

Description: Returns current statistics about a playfield

Answer to Request: Request_Playfield_Stats.

Param data: PlayfieldStats

Event_Playfield_Loaded[edit | edit source]

Description: Triggered when a playfield is loaded.

Param data: PlayfieldLoad

Event_Playfield_Unloaded[edit | edit source]

Description: Triggered when a playfield is unloaded.

Param data: PlayfieldLoad

Event_Dedi_Stats[edit | edit source]

Description: Returns current statistics about the game

Answer to Request: Request_Dedi_Stats.

Param data: DediStats

Event_GameEvent[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Description: Returns the player coordinates and rotation.

Answer to Request: Request_Entity_PosAndRot.

Param data: IdPositionRotation

Event_Faction_Changed[edit | edit source]

Description: Triggered when a structure changes its faction.

Param data: FactionChangeInfo

Event_Get_Factions[edit | edit source]

Description: Returns faction information.

Answer to Request: Request_Get_Factions.

Param data: FactionInfoList

Event_Statistics[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

Param data: Id

Event_ChatMessage[edit | edit source]

Description: Triggered when a player writes a chat.

Param data: ChatInfo

Event_Structure_BlockStatistics[edit | edit source]

Description: Returns all blocks of a structure.

Answer to Request: Request_Structure_BlockStatistics.

Param data: IdStructureBlockInfo

Event_AlliancesAll[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Description: Returns all banned players.

Answer to Request: Request_GetBannedPlayers.

Param data: BannedPlayerData

Event_TraderNPCItemSold[edit | edit source]

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

Param data: TraderNPCItemSoldInfo

Event_Player_GetAndRemoveInventory[edit | edit source]

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[edit | edit source]

Description: PDA chapter activated/deactivated/completed

Answer to Request: N/A

Param data: PdaStateInfo

Event_Playfield_Entity_List[edit | edit source]

Description: Returns all entitys of a playfield.

Answer to Request: Request_Playfield_Entity_List

Param data: PlayfieldEntityList

Event_DialogButtonIndex[edit | edit source]

Description: Returns the state of the clicked button

Answer to Request: Request_ShowDialog_SinglePlayer

Param data: IdAndIntValue