IPC protocol - TheXTech/TheXTech GitHub Wiki

The IPC protocol is fully compatible with Moondust Engine. To begin the IPC session, it's need to start the game with an -i or --interprocessing flag. A whole communication process does use of stdin and stdout asynchronously to exchange messages between client (Editor) and server (Engine). Every sending message must be encoded with a BASE64 and every sending message must end with a new-line character '\n'. When engine loading will be completed, a notify message will be sent to the Editor to confirm a readiness to receive a level data.

Caution: You should never print anything using stdout, this will break the protocol workflow! Use the stderr to print anything like logs or notifications.

Low level

Sending message

  • Format a command string.
  • Encode the message string with the BASE64 algorithm.
  • Append the \n character to the end.
  • Write a result into the pipe.

Receive message

  • While pipe input reading, collect all input data into the buffer until receiving a new line character \n which shouldn't be written into the buffer.
  • Decode string from BASE64.
  • Do command the parse of a command string.

Commands

All commands should work asynchronously.

Editor (client-side)

There are Editor side commands which can be executed by a message sent from Engine into Editor:

  • CMD:CONNECT_TO_ENGINE - A first Engine message which notifies that it's ready to receive a level data. When Editor receives this command, it should send an SEND_LVLX: <full path to level> message with a following raw level data (see Engine's messages). Otherwise, Engine will send this message again, and later, Engine will be closed with a timeout error message.
  • CMD:ENGINE_CLOSED - This command notifies that Engine preparing to be closed and disconnects the IPC interface.
  • CMD:NUM_STARS <num stars> - This command returns the number of collected stars back to the Editor.
  • CMD:TAKEN_BLOCK\nTAKEN_BLOCK_END\n<PGE-X block data> - This command notifies Editor about the taken block object at the game to pop-up the properties box you can use to change its properties and place back into the game. Block data should be in the same as in the LVLX file, for example:
BLOCK\n
ID:437;X:-199552;Y:-200288;W:320;H:224;AS:0;
BLOCK_END\n
  • CMD:TAKEN_BGO\nTAKEN_BGO_END\n<PGE-X BGO data> - This command notifies Editor about the taken background object at the game to pop-up the properties box you can use to change its properties and place back into the game. BGO data should be in the same format as in the LVLX file.
  • CMD:TAKEN_NPC\nTAKEN_NPC_END\n<PGE-X NPC data> - This command notifies Editor about the taken NPC at the game to pop-up the properties box you can use to change its properties and place back into the game. NPC data should be in a same format as in LVLX file.
  • CMD:PLAYER_SETUP_UPDATE <pid> <cr> <st> <vt> <vs> - This command returns the last playable character state that can be used again in the next test. pid - number of the player (1 or 2); cr - Number of character; st - Number of state; vt - Type of the vehicle/mount; vs - State of the vehicle/mount. Note: in a two-player mode, this command will be sent twice: one sent command per player.

Engine (server-side)

Engine together with an ability to receive raw data of a scratch level file and run it, also has a set of useful commands that can be sent from Editor into Engine.

  • SEND_LVLX: <full path to level>\n - A greeting message, sent by Editor after initial Engine's request. After sending of this message, Editor must send a full dump of a full level file in the PGE-X LVLX format as a message (means, this dump must be base64-encoded). It's allowed to split level data into multiple small pieces which can be sent sequentially as a separated messages. When all level data was sent, Editor must send the PARSE_LVLX message to confirm that level transferring have been completed. Engine will start a parsing of received level data and will start a game if no errors occurred.
  • MSGBOX: <any text> - Show a pop-up message box with a given raw text while level testing game is running.
  • CHEAT: <cheat code string> - Execute a cheat code.
  • PLACEITEM: BLOCK_PLACE\nBLOCK_PLACE_END\n<PGE-X block data> - (Magic Hand mode only) - Turn the placing mode of block with given propertoes, or alter properties of a holding block entry. Block data should be in the same as in the LVLX file, for example:
BLOCK\n
ID:437;X:-199552;Y:-200288;W:320;H:224;AS:0;
BLOCK_END\n
  • PLACEITEM: BGO_PLACE\nBGO_PLACE_END\n\n<PGE-X BGO data> - (Magic Hand mode only) - Turn the placing mode of background object (BGO) with given properties, or alter properties of a holding BGO entry. BGO data should be in the same format as in the LVLX file.
  • PLACEITEM: NPC_PLACE\nNPC_PLACE_END\n\n<PGE-X NPC data> - (Magic Hand mode only) - Turn the placing mode of non-playable character (NPC) with given propertoes, or alter properties of a holding NPC entry. NPC data should be in a same format as in LVLX file.
  • SET_LAYER: <name of layer> - Change a destination layer of currently placing object. (Added in April 19, 2020)
  • SET_NUMSTARS: <number> - Specify the number of collected starts to verify the work of stars-dependent features and scripts. (Since TheXTech 1.3.5.2)
⚠️ **GitHub.com Fallback** ⚠️