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.
- 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.
- 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.
All commands should work asynchronously.
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 anSEND_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 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 thePARSE_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)