Level Editing

gd.py provides convenient API for creating and editing levels.

You can create objects like this:

from gd.api import Object

obj = Object(id=1, x=150, y=150).add_groups(1)
# <Object id=1 x=150 y=150 groups={1}>

string = some_object.dump()
# "1,1,2,150,3,150,57,1"

And open editor, like the following:

from gd.api import Editor

# assume we have our "some_object" from above

editor = Editor()

editor.add_objects(some_object)

string = editor.dump()
# "...;1,1,2,150,3,150,57,1;"

There is an option to load the level’s editor:

import gd

client = gd.Client()

level = client.run(client.get_level(30029017))

editor = level.open_editor()

gd.py also gives some helpers in case user does not know some values:

from gd.api import Object

some_object = Object(x=150, y=150, lock_to_player_x=True, target_group_id=1)
# <Object id=1 x=150 y=150 target_group_id=1 lock_to_player_x=True>

some_object.set_id("trigger:move")  # move trigger
# <Object id=901 x=150 y=150 target_group_id=1 lock_to_player_x=True>

some_object.set_easing("sine_in_out")
# <Object id=901 x=150 y=150 easing=Easing.SINE_IN_OUT target_group_id=1 lock_to_player_x=True>

gd.api.get_id(string: str, into_enum: bool = False, delim: str = ':') → Any

Calculate required value from the given directive string.

The format is, as follows: class:name, e.g. special:h. Spaces around : are allowed.

Parameters

• string (str) – Directive to get value from.

• into_enum (bool) – Whether to convert found value to enum. By default, False.

• delim (str) – Character to split given directive string with. It is not recommended to pass this argument to the function.

Returns

The value found, if any.

Return type

Any

Raises

EditorError – Failed to convert directive to the value.

Editor

class gd.api.Editor(*objects: gd.api.struct.Object, **header_args)

Editor interface of gd.py.

Editor can be created either by hand, from decoded level’s data, or taken from a level itself.

classmethod load_from(callback: Union[GameLevel, Level, gd.api.struct.LevelAPI], attribute: str) → Editor

Load the editor from Level, LevelAPI or GameLevel, and set a callback to dumb the editor to it. This method is intented to be used internally.

classmethod from_object_iterable(objects: Iterable[gd.api.struct.Object], **header_args) → gd.api.editor.Editor

Create the editor from objects, constructing header with header_args.

classmethod from_string(data: Union[bytes, str], delim: str = ';', ignore_empty: bool = True) → gd.api.editor.Editor

Create the editor from data string.

classmethod load(data: Union[bytes, str], delim: str = ';', ignore_empty: bool = True) → gd.api.editor.Editor

Create the editor from data string.

set_header(header: gd.api.struct.Header) → gd.api.editor.Editor

Set header of Editor instance to header.

get_header() → gd.api.struct.Header

Get header of Editor instance.

copy_header() → gd.api.struct.Header

Copy header of Editor instance.

clone_header() → gd.api.struct.Header

Clone header of Editor instance.

get_groups() → Set[int]

Fetch all used groups in Editor instance and return them as a set.

get_color_ids() → Iterable[int]

Fetch all used color IDs in Editor instance and return them as a set.

get_free_group() → Optional[int]

Get next free group of Editor instance. None if not found.

get_free_color_id() → Optional[int]

Get next free color ID of Editor instance. None if not found.

get_portals() → List[gd.api.struct.Object]

Fetch all portals / speed triggers used in this level, sorted by position in level.

get_speeds() → List[gd.api.struct.Object]

Fetch all speed changes used in this level, sorted by position in level.

get_x_length() → float

Get the X position of a last object. Default is 0.

get_start_speed() → gd.enums.Speed

Get speed from a header, or return normal speed.

get_length(dx: Optional[float] = None) → float

Calculate length of the level in seconds.

get_color(directive_or_id: Union[int, str]) → Optional[gd.api.struct.ColorChannel]

Get color by ID or special directive. None if not found.

get_colors() → gd.api.struct.ColorCollection

Return a reference to colors of the Editor instance.

set_colors(colors: gd.api.struct.ColorCollection) → gd.api.editor.Editor

Set colors of the Editor instance to colors.

property colors

Return a reference to colors of the Editor instance.

copy_colors() → gd.api.struct.ColorCollection

Copy colors of the Editor instance.

clone_colors() → gd.api.struct.ColorCollection

Clone colors of the Editor instance.

add_colors(*colors: gd.api.struct.ColorChannel) → gd.api.editor.Editor

Add colors to the Editor.

remove_colors(*colors: gd.api.struct.ColorChannel) → gd.api.editor.Editor

Remove colors from the Editor.

get_objects() → List[gd.api.struct.Object]

Return a reference to object of the Editor instance.

set_objects(objects: List[gd.api.struct.Object]) → gd.api.editor.Editor

Set objects of the Editor instance to objects.

add_objects(*objects: gd.api.struct.Object) → gd.api.editor.Editor

Add objects to self.objects.

remove_objects(*objects: gd.api.struct.Object) → gd.api.editor.Editor

Remove objects from the Editor instance.

copy_objects() → List[gd.api.struct.Object]

Copy objects of the Editor instance.

clone_objects() → List[gd.api.struct.Object]

Clone objects of the Editor instance.

to_string(delim: str = ';') → str

Dump all objects and header into a level data string.

dump(delim: str = ';') → str

Dump all objects and header into a level data string.

copy() → gd.api.editor.Editor

Return a copy of the Editor instance.

clone() → gd.api.editor.Editor

Return a clone of the Editor instance.

Header

class gd.api.Header(*, use_default: bool = True, **kwargs)

HSV

class gd.api.HSV(*, use_default: bool = True, **kwargs)

A class that represents HSV - Hue, Saturation, Value (Brightness) options.

Below is a table that shows how S and V depend on whether they are checked:

value range	false	true
s range	[0, 2]	[-1, 1]
v range	[0, 2]	[-1, 1]

Parameters

• h (int) – Hue integer value in range [-180, 180].

• s (float) – Saturation float value in range [0, 2] or [-1, 1] depending on s_checked.

• v (float) – Value (Brightness) float value in range [0, 2] or [-1, 1] depending on v_checked.

• s_checked (bool) – Whether s is checked.

• v_checked (bool) – Whether v is checked.

ColorChannel

class gd.api.ColorChannel(directive: Optional[str] = None, **kwargs)

ColorCollection

class gd.api.ColorCollection(iterable: Optional[Iterable[gd.api.struct.ColorChannel]] = None, use_default: bool = True)

remove(directive_or_id: Union[int, str]) → None

Remove an element from a set; it must be a member.

If the element is not a member, raise a KeyError.

copy() → gd.api.struct.ColorCollection

Return a shallow copy of a set.

difference(other: Iterable[gd.api.struct.ColorChannel]) → gd.api.struct.ColorCollection

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

intersection(other: Iterable[gd.api.struct.ColorChannel]) → gd.api.struct.ColorCollection

Return the intersection of two sets as a new set.

(i.e. all elements that are in both sets.)

symmetric_difference(other: Iterable[gd.api.struct.ColorChannel]) → gd.api.struct.ColorCollection

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

union(other: Iterable[gd.api.struct.ColorChannel]) → gd.api.struct.ColorCollection

Return the union of sets as a new set.

(i.e. all elements that are in either set.)

update(other: Iterable[gd.api.struct.ColorChannel]) → gd.api.struct.ColorCollection

Update a set with the union of itself and others.

Object

class gd.api.Object(*, use_default: bool = True, **kwargs)