/APCpp

Primary LanguageC++GNU Lesser General Public License v2.1LGPL-2.1

APCpp

C++ Library for Clients interfacing with the Archipelago Multi-Game Randomizer

Usage

Initialization

Run one of the AP_Init functions as the first call to the library:

  • AP_Init(const char*, const char*, const char*, const char*) with IP, Game Name, Slot Name and password (can be "")
  • AP_Init(const char*) with the filename corresponding to a generated single player game.

Then, you must call the following functions (any order):

  • AP_SetItemClearCallback(void (*f_itemclr)()) with a callback that clears all item states
  • AP_SetItemRecvCallback(void (*f_itemrecv)(int,bool)) with a callback that adds the item with the given ID (first parameter) to the current state. The secound parameter decides whether or not to notify the player
  • AP_SetLocationCheckedCallback(void (*f_locrecv)(int)) with a callback that marks the location with the given id (first parameter) as checked.

Optionally, for finer configuration:

  • AP_EnableQueueItemRecvMsgs(bool)` Enables or disables Item Messages for Items received for the current game. Alternative to using the game's native item reception handler, if present. Defaults to on.

Optionally, for DeathLink:

  • AP_SetDeathLinkSupported(bool) Enables or disables DeathLink from the Library. Defaults to off. NOTE: If on, expects DeathLink data from Archipelago.
  • AP_SetDeathLinkRecvCallback(void (*f_deathrecv)()) Alternative to manual query. Optional callback to handle DeathLink.

Optionally, if slot data is required:

  • AP_RegisterSlotDataIntCallback(std::string, void (*f_slotdata)(int)) Add a callback that receives an int from slot data with the first parameter as its key.
  • AP_RegisterSlotDataMapIntIntCallback(std::string, void (*f_slotdata)(std::map<int,int>)) Add a callback that receives an int to int map from slot data with the first parameter as its key.

Finally, call AP_Start()

Operation during runtime

When the player completes a check, call AP_SendItem(int) with the Item ID as the parameter. When the player completes the game, call AP_StoryComplete.

DeathLink

If DeathLink is supported, you have multiple ways of using it:

  • Regularly call AP_DeathLinkPending() and check the return value. If true, kill the player and call AP_DeathLinkClear() (Preferably after a short time. Faulty clients can send multiple deaths in quick succession. Ex.: Clear only after player has recovered from death).
  • Handle death using a DeathLink callback (Registration described in Initialization)

Messages

Messages can be received from the Archipelago Server and this Library, such as Messages describing which item was sent, who was responsible for a Death received with DeathLink, etc. To receive messages:

  • Check if message is available using AP_IsMessagePending()
  • Receive with AP_GetLatestMessage(). This returns an AP_Message struct with a type and preconfigured presentable text for this message. If you want the game client to have more details for the message (for example to create a custom text) any non-plaintext type message can be casted to an AP_TYPEMessage with some type-specific struct members providing additional information for the given message.
  • Clear the latest message with AP_ClearLatestMessage().

Building

Clone the Repo recursively!

Linux

  • Create a folder build
  • cd build
  • cmake ..
  • cmake --build .

Windows

  • Create a folder build
  • Enter the folder
  • cmake .. -DWIN32=1 (If on MinGW, also add -DMINGW=1. If zlib is not installed add -DUSE_ZLIB=OFF)
  • cmake --build .