gmdbuilder

Appearance

Getting Started ​

Installation ​

Install the latest release from PyPI:

bash
pip install gmdbuilder

Or install the latest development version directly from GitHub:

bash
pip install git+https://github.com/LXtreme/gmdbuilder.git

Python 3.12 or newer is required.

IDE setup ​

gmdbuilder is designed to be used with a type checker. Without one, you lose out on much of the value of the type system.

I heavily recommend Zed. It is a new high-performance feature rich IDE written in rust. More importantly it comes with basedpyright by default. I personally consider Zed to be a true 'VS Code killer'.

However any IDE with good type checking and LSP support will suffice. In VS Code, make sure to have Pylance.

A good python LSP setup will give all the static type checking for objects/properties.

Loading a level ​

There are two ways to load a level instance.

From a .gmd file (GDShare) ​

Provide the file path:

python
from gmdbuilder import Level

level = Level.from_file("my_level.gmd")

From live editor (WSLiveEditor) ​

This connects to the WSLiveEditor mod while a level is open.

python
level = Level.from_live_editor()

Objects ​

Once a level is loaded, level.objects gives you the full list of objects as a Python list you can iterate, slice, and filter normally:

python
all_objects = level.objects

You work with these using the obj_prop namespace, which gives every key a readable name:

python
from gmdbuilder import obj_prop

obj = all_objects[0]
obj[obj_prop.X] = 0 # same as obj["a2"]
print(obj[obj_prop.X]) # prints 0
print(obj[obj_prop.GROUPS])  # same as obj["a57"], returns a set[int]

Property keys are organized by trigger type under obj_prop.Trigger.*:

python
# All literal strings:
obj_prop.Trigger.Move.TARGET_ID  # "a51"
obj_prop.Trigger.Move.DURATION   # "a10"
obj_prop.Trigger.Spawn.DELAY     # "a63"
obj_prop.Trigger.Color.CHANNEL   # "a23"

Object generation and editing is the main purpose of the tool, so there are many other helpful features to make this easier to scale.

See Add & Edit Objects, Trigger Wrappers and Context Managers.

Validation ​

Every assignment to an object property is validated immediately — not at export time.

python
obj[obj_prop.Trigger.Move.DURATION] = "fast"  # raises ValueError: wrong type
obj[obj_prop.X] = 100                         # ok, X accepts int or float
obj[obj_prop.ID] = 999                        # raises KeyError: ID is read-only

Validation checks that:

  • The key is allowed on this object type
  • The value is the correct Python type
  • Numeric values are within GD's accepted range

Individual checks can be disabled through the setting object. See Validation Settings for details.

Exporting ​

Every object added via level.objects.append() or extend() is automatically stamped with the level's tag_group. On the next load, any objects carrying that group are stripped — so re-running your script never duplicates objects.

To a file ​

python
# Export to a new file
level.export_to_file("my_level_updated.gmd")

To the live editor ​

python
level.export_to_live_editor()

Exporting replaces the level string with the current state of level.objects and level.color.

Next steps ​

gmdbuilder — built in collaboration with HDanke