Backend - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

In the LateralGM sphere, backend is the term used to refer to raw data and the way it is communicated, based off the backend of the Three-Tier Architecture model, utilized in order to keep the programs modular and inter-replaceable.

Identification

It may be tempting to think of the three tiers as LateralGM (frontend UI), ENIGMA and its Toolchain executables (functionality), and the resulting Exe (backend data), but this is unintentional and misleading - it would be more appropriate to think of the three tiers within LateralGM itself, with ENIGMA acting as an interested third-party. In this paradigm, the three tiers are as follows:

  • Backend/Data - LGM's raw data to store concrete components of the game, in memory or in files.
  • Functionality/Logic - A set of actions that may be performed on the data to interact with it indirectly, rather than directly.
  • Frontend/Presentation - LGM's GUI presentation of the game. Any changes to the backend data initiated by a GUI change should be done through a functionality-tier action, rather than acted on the data directly.

Use

The separation of these tiers allows the frontend tier (the GUI) to be stripped off and replaced without modifying either of the other two tiers, or stripping off and replacing both the frontend and the functionality, so as to completely reorient the use of the data for other purposes, such as compiling.

Portability

See also Plugin for the intermediate step by which LGM and ENIGMA communicate. The Plugin is responsible for populating the backend and communicating it to ENIGMA.

LGM is entirely written in Java, and so is the backend. To facilitate the translation of this data into another language, such as C++, we either export the data into an agreed-upon file format, duplicate the data into a compatible memory format (namely, POD - Plain Old Data), or find some way for the other language to understand our Java data types. The last method is usually not employed because of its obvious difficulty, and the first method induces a lot of overhead, so the commonly employed method is to duplicate the data into POD. Live (populated) data can then be communicated, such as through DLL methods.

Plain Old Data (POD)

Many structures in Java are overly complex for a lower-level language like C++, providing excess fields and redundancies which may make the data easier to interact with, but harder to convert into a compatible memory format, especially when that conversion is done ad-hoc (as is usually the case). For instance, a linked list is great for interactive purposes, but for communicating the underlying data as-is, an array is sufficient and easier to replicate than the entire linked list. To further emphasize this, JNA, a popular Java library for inter-language communication (that is, getting Java to call a DLL), converts an array with relative ease, but doesn't recognize a linked list unless it's spelled out for it. The idea of POD is that you can identify every nail and wooden board that went into the construction of the house, even if the house itself is divided into sub-structures, and each sub-structure further sub-divided. Sometimes this is referred to as trivially-copyable.

ENIGMA Backend

ENIGMA provides a backend of Plain Old Data, both C-side (CompilerSource/backend/) and Java-side (pluginsource/org/enigma/backend/). In addition, a number of functions are provided to allow the two to interface interactively and communicate live data. The root structure, or the structure of greatest complexity which is populated by almost every other structure, is EnigmaStruct, and its fields are fairly self-explanatory. ENIGMA's dll API provides a number of functions with which to work on this data, such as syntax checking or compiling it. The definitions of these functions reside in what is called the EnigmaDriver. Additionally, a toolkit of callback functions, defined in EnigmaCallbacks, give progress reports on the lengthy functions or provide additional Java functionality where C++ may be lacking.

EnigmaDriver

The dll is initialized with the callback toolkit via a call to

String libInit(EnigmaCallbacks ef);

which will return null on success or the error string on failure (e.g. one of the toolchain executables, like G++, was not found or behaved unexpectedly).

At this point, you may now communicate with the DLL to do one of the following:

  • Inform of modifications to settings and definitions.
  • Retrieve available functions, global variables, etc.
  • Check the syntax of a string of EDL.
  • Compile the data.

A formal and fully-volatile specification can be found in the EnigmaDriver main article.