LateralGM:Packages - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

As of r345, LateralGM is comprised of a hierarchy of folder-like structures called packages that keep the project organized. There are 9 primary packages and within some of these packages are sub-packages.

  • Developers should at least familiarize themselves with packages denoted [1]
  • Users who wishes to make some basic modifications without any knowledge of Java would only find themselves in packages denoted [2]
  • /org/lateralgm Basically the root directory of the project, ignoring the directory containing the meta-inf and licensing information.
    • compare Largely comprised of a class-comparison module adapted from elsewhere, licensed under the GPL-compatible Apache License. The classes in here are used to determine if the end-user has changed a resource, so that they can revert or commit those changes to their game.
    • components[3] Custom components, called Beans, are stored here. These are components that we've created where the components provided by Java were insufficient, such as IntegerField, or components specialized for LGM that Java could not have been expected to provide, such as ResourceMenu. Developers should familiarize themselves with the components provided in this class for their convenience.
      • impl Custom components implemented by other components. For example, IntegerDocument is the document behind IntegerField. Two classes in here are most worth mentioning. The first being ResNode, which is a node for the Resource Tree, and determines how to open resource editors. The second is EventNode, which is a node representing an event in the Event Tree (unlike GM, which did not evolve a tree structure to represent events).
      • mdi Handles the multi-window desktop interface, or the MDI, which is the big rectangle to the right of the Resource Tree. The actual subframes that go in here are not in this package, but in the subframes package which will be covered later.
      • visual Components which are primarily for visual appeal. These usually handle their own painting and have minimal interaction with input devices such as the keyboard and mouse (RoomEditor being an exception).
    • file Responsible for anything dealing with the backend of reading and writing files, and handling the Gm File Format. Library information does not reside here, but in a library package which will be mentioned later. Also worth noting here is the very pretty red ball default icon used for games that do not apply their own icon, in both rendered (png) and source (svg) form. We usually only touch this package when we want to adapt a new format, improve speed, or fix a bug. Files in this package should contain no or minimal UI information, so that they can easily be adapted by another project that wishes to create its own UI. This is dependent on the resources back-end which will be covered below.
      • iconio Largely comprised of a icon input/output module created by a Christian Treber, used with permission and adapted for the GPL. This is mostly for dealing with the icon that the end-user applies to the game. A lot of classes for dealing with a little task, because ICO isn't exactly the most java-friendly format.
    • icons[4] Exclusively contains the icons used throughout the LGM interface. These can be swapped out with your own icon of the same filename without recompiling and LGM will gladly use that instead, no questions asked. Please only use icons with permission of the author and/or provided under a GPL permissive license. This package does not contain icons used in libraries, as those are stored within the libraries themselves.
      • actions Icons that invoke some sort of action, such as loading a file, copying text, etc.
      • events Icons pertaining to the Event Tree
      • restree Icons pertaining to Resources and the Resource Tree
    • jedit Largely comprised of the code editing software known as JEdit, adapted from a 1999 version due to its small filesize and no bulk, although as such, it was also lacking in many features which we are slowly re-implementing. It was licensed under a very permissive GPL-compatible license. This package is used for the code editors seen when using a Script, the Execute a Piece of Code action, and Instance and Room Creation Code.
    • main[5][6] Contains the key classes, such as the runner, an event listener (that is, Java is Event-driven, not GM Event), Preferences, Utility methods, the icon lookup sheet, and the logo/splash screen, in both rendered (png) and source (svg) form. Due to its key role, editing of classes in here should be done with caution lest you break something. Also worth noting, aside from the icon lookup sheet, is the preferences.properties, where LGM stores all its preferences so that you can change them without recompiling.
    • messages[7] Language support. Strings used in LGM are kept in a central external .properties file so that a user can modify a string without recompiling, such as to fix typos or provide translations to other languages.
    • resources[8] Back-end classes which should contain no interface or logic. These are simply for holding information. As such, any other project could easily grab the back-end and apply their own Interface in case they don't like ours. The only exception here is in the library package, which contains logic for loading libraries.
      • library Self-explanatory. Used to load in and manage GM libraries in both GM's lib format and LGM's ergonomic lgl format. Library, LibArgument, and LibAction are back-end classes, LibManager and LibFormatException are logic classes which contain no UI information.
        • lib Contains the base libraries in lgl format. LGL is a LGM-specific format that was designed to contain all the information that a GM LIB does, but in 1/10th of the space. GM's default libraries take up about 1000KB of space. LGL's default libraries, which serve the same purpose, with some slight modifications so as to avoid copyright infringement, take up about 100KB of space. Unfortunately, as of this writing, no complete documentation and no modification program is available for the LGL format, however the LibManager contains all the necessary code to load in the lgl files and support their format, so if need be, you can learn from or use that until documentation or a modification program is made available.
      • sub More back-end classes which are not directly resources, but are sub-components of resources, such as Arguments, Actions, Tiles, etc.
    • subframes[9] UI and related logic for editing Resources. Called subframes because they are frames that usually reside (or subside) within the MDI (thus, they usually extend MDIFrame), which is a part of the main frame. Most of a developers time is spent in these classes. All of the primary resource frames are subclasses of ResourceFrame. SubframeInformer contains ways to listen for, and be informed of when a subframe is created. It is primarily used for plugins.

Undocumented Packages

In r346 and r347, Quadduc introduced the ui and util packages and their subpackages. He did not provide an explanation, and this article's writers have not bothered to understand/update this article with their purposes yet. It seems that they are mostly irrelevant for most development purposes.

Understanding

Within each of these packages you will find classes and files which have names that are usually self-explanatory. If not, feel free to look inside them and figure out what they do. Our apologies that for a vast majority of the project there is little or no documentation, but for the amount of effort that we put into writing these classes, you could at least put a little effort into reading them and getting a real understanding of what the class does, not just some overview. We have done our best to comment areas that we feel are either confusing, or where the code does not really describe the desired effect, or to give you a hint where as to what you'll need if you wish to dive in at certain common spots, such as plugins.

Questions

Of course, if you do have further questions about any of the classes, feel free to contact one of us, or perhaps more appropriate, anyone in the copyrights for that class. Usually the first person in the copyrights is the person who contributed the most to that class.

  1. Developer packages

  2. User packages.