Game API¶
gd.py implements an interface to interact with saves of Geometry Dash.
Save¶
Warning
It is recommended to do a backup before working with saves.
Main save/load functionality is contained in SaveUtil
,
exported and intended to be used as gd.api.save
instance.
Example of loading a local database:
import gd
database = gd.api.save.load()
That simple? Yeah, that’s python! Everything is simple.
-
class
gd.api.
SaveUtil
[source]¶ -
await
load_async
(*args, **kwargs) → gd.api.save.Database[source]¶ This function is a coroutine.
Asynchronously load a save.
This function is normally used for local GD management. Typical use-case might be, as follows:
database = await gd.api.save.load_async()
Warning
Please note that
main_file
andlevels_file
can NOT beNone
.- Parameters
main (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing main part of the save.levels (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing levels part of the save.main_file (Union[
str
,pathlib.Path
]) – Path to a file containing main part of the save. Applied whenmain
is a directory.levels_file (Union[
str
,pathlib.Path
]) – Path to a file containing levels part of the save. Applied whenlevels
is a directory.
- Returns
Loaded Database. If any of the files not found, returns an empty
gd.api.Database()
.- Return type
-
load
(*args, **kwargs) → gd.api.save.Database[source]¶ Load a save.
This function is normally used for local GD management. Typical use-case might be, as follows:
database = gd.api.save.load()
Warning
Please note that
main_file
andlevels_file
can NOT beNone
.- Parameters
main (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing main part of the save.levels (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing levels part of the save.main_file (Union[
str
,pathlib.Path
]) – Path to a file containing main part of the save. Applied whenmain
is a directory.levels_file (Union[
str
,pathlib.Path
]) – Path to a file containing levels part of the save. Applied whenlevels
is a directory.
- Returns
Loaded Database. If any of the files not found, returns an empty
gd.api.Database()
.- Return type
-
await
dump_async
(*args, **kwargs) → None[source]¶ This function is a coroutine.
Asynchronously dump a save.
This function is normally used for local GD management. Typical use-case might be, as follows:
await gd.api.save.dump_async(database)
Warning
Please note that
main_file
andlevels_file
can NOT beNone
.- Parameters
db (
api.Database
) – Database object to dump.main (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing main part of the save.levels (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing levels part of the save.main_file (Union[
str
,pathlib.Path
]) – Path to a file containing main part of the save. Applied whenmain
is a directory.levels_file (Union[
str
,pathlib.Path
]) – Path to a file containing levels part of the save. Applied whenlevels
is a directory.
-
dump
(*args, **kwargs) → None[source]¶ Dump a save.
This function is normally used for local GD management. Typical use-case might be, as follows:
gd.api.save.dump(database)
Warning
Please note that
main_file
andlevels_file
can NOT beNone
.- Parameters
db (
api.Database
) – Database object to dump.main (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing main part of the save.levels (Optional[Union[
str
,pathlib.Path
]]) – Path to a file/directory containing levels part of the save.main_file (Union[
str
,pathlib.Path
]) – Path to a file containing main part of the save. Applied whenmain
is a directory.levels_file (Union[
str
,pathlib.Path
]) – Path to a file containing levels part of the save. Applied whenlevels
is a directory.
-
await
to_string_async
(*args, **kwargs) → str[source]¶ This function is a coroutine.
Asynchronously dump a save into string(s).
This might be used when you need to transfer your save a stream.
- Parameters
db (
api.Database
) – Database object to dump.connect (
bool
) – Whether to join all strings with;
into one string. Default isTrue
.xor (
bool
) – Whether to apply XOR after zipping the save. (GD does that for local files) Defaults toFalse
.
- Returns
A string or a tuple of strings containing the save.
- Return type
-
to_string
(*args, **kwargs) → str[source]¶ Dump a save into strings(s).
This might be used when you need to transfer your save a stream.
- Parameters
db (
api.Database
) – Database object to dump.connect (
bool
) – Whether to join all strings with;
into one string. Default isTrue
.xor (
bool
) – Whether to apply XOR after zipping the save. (GD does that for local files) Defaults toFalse
.
- Returns
A string or a tuple of strings containing the save.
- Return type
-
await
from_string_async
(*args, **kwargs) → gd.api.save.Database[source]¶ This function is a coroutine.
Asynchronoulsy load save from strings.
- Parameters
- Returns
Database object containing loaded data.
- Return type
-
from_string
(*args, **kwargs) → gd.api.save.Database[source]¶ Load save from strings.
- Parameters
- Returns
Database object containing loaded data.
- Return type
-
make_db
(main: str = '', levels: str = '') → gd.api.save.Database[source]¶ Create a database from string parts.
This method should be used if you already have XML strings, or it can be used as a more understandable way of doing
gd.api.Database()
creation:db = gd.api.save.make_db() # or supply arguments
- Parameters
- Returns
Database object containing loaded data.
- Return type
-
await
Database¶
Database is python interface to saves of Geometry Dash.
db = gd.api.make_db()
print(db.load_my_levels())
# LevelCollection[<LevelAPI id=... version=... name=...>, ...]
levels = db.levels
# <Part len=...>
# {"LLM_01": {...}, "LLM_02": ..., ...}
print(levels.get("LLM_02", 0))
-
class
gd.api.
Part
(stream: str = typing.Union[bytes, str], default: Optional[Dict[str, Any]] = None)[source]¶
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, groups={1})
# <Object id=1 x=150 y=150 groups={1}>
string = obj.dump()
# '1,1,2,150,3,150,57,1'
And open editor, like the following:
from gd.api import Editor
# assume we have our 'obj' from above
editor = Editor()
editor.add_objects(obj)
string = editor.dump()
# '<some_data>;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
o = 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>
o.set_id('trigger:move') # move trigger
# <Object id=901 x=150 y=150 target_group_id=1 lock_to_player_x=True>
o.set_easing('sine_in_out')
# <Object id=901 x=150 y=150 easing=Easing.SineInOut (SineInOut) target_group_id=1 lock_to_player_x=True>
-
gd.api.
get_id
(x: str, ret_enum: bool = False, delim: str = ':') → Any[source]¶ Calculate required value from the given directive
x
.The format is, as follows:
class:name
, e.g.special:h
. Spaces around:
are allowed.- Parameters
- Returns
The value found, if any.
- Return type
Any
- Raises
EditorError – Failed to convert directive to the value.
Editor¶
-
class
gd.api.
Editor
(*objects: Sequence[gd.api.struct.Object], **header_args)[source]¶ Editor interface of gd.py.
Editor can be created either by hand, from decoded level’s data, or taken from a level itself.
-
set_header
(header: gd.api.struct.Header) → gd.api.editor.Editor[source]¶ Set header of Editor instance to
header
.
-
get_groups
() → Iterable[int][source]¶ Fetch all used groups in Editor instance and return them as a set.
-
get_color_ids
() → Iterable[int][source]¶ Fetch all used color IDs in Editor instance and return them as a set.
-
get_free_group
() → Optional[int][source]¶ Get next free group of Editor instance.
None
if not found.
-
get_free_color_id
() → Optional[int][source]¶ Get next free color ID of Editor instance.
None
if not found.
-
get_portals
() → List[gd.api.struct.Object][source]¶ Fetch all portals / speed triggers used in this level, sorted by position in level.
-
get_speed_portals
() → List[gd.api.struct.Object][source]¶ Fetch all speed triggers used in this level, sorted by position in level.
-
get_length
(x: Optional[Union[float, int]] = None) → float[source]¶ Calculate length of the level in seconds.
-
get_color
(directive_or_id: Union[int, str]) → Optional[gd.api.struct.ColorChannel][source]¶ Get color by ID or special directive.
None
if not found.
-
get_colors
() → gd.api.struct.ColorCollection[source]¶ Return a reference to colors of the Editor instance.
-
add_colors
(*colors: Sequence[Union[Tuple[int, int, int], int, gd.api.struct.ColorCollection]]) → gd.api.editor.Editor[source]¶ Add colors to the Editor.
-
get_objects
() → List[gd.api.struct.Object][source]¶ Return a reference to object of the Editor instance.
-
add_objects
(*objects: Sequence[gd.api.struct.Object]) → gd.api.editor.Editor[source]¶ Add objects to
self.objects
.
-
map
(function: Callable[[gd.api.struct.Object], Any]) → map[source]¶ map
: Same as callingmap
onself.objects
.
-
filter
(function: Callable[[gd.api.struct.Object], Any]) → filter[source]¶ filter
: Same as callingfilter
onself.objects
.
-
Enums¶
-
class
gd.api.
ObjectDataEnum
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing contents of an object.
-
class
gd.api.
ColorChannelProperties
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing contents of a color channel.
-
class
gd.api.
PlayerColor
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration for player color setting.
-
class
gd.api.
CustomParticleGrouping
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration for particle grouping.
-
class
gd.api.
CustomParticleProperty1
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration for particle system.
-
class
gd.api.
Easing
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing easing of a moving object (used in move/rotate triggers).
-
class
gd.api.
PulseMode
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing mode of a pulse trigger.
-
class
gd.api.
InstantCountComparison
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing instant count comparison check.
-
class
gd.api.
OrbType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing IDs of orb objects.
-
class
gd.api.
PadType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing IDs of pad objects.
-
class
gd.api.
PortalType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing IDs of portal or speed change objects.
-
class
gd.api.
PickupItemMode
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing mode of a pickup trigger.
-
class
gd.api.
PulseType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing type of pulse trigger target.
-
class
gd.api.
SpecialBlockType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing IDs of special objects (e.g. S, H, etc).
-
class
gd.api.
SpecialColorID
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing IDs of special colors (e.g. BG, Line, etc).
-
class
gd.api.
TargetPosCoordinates
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing modes for a targetted move trigger.
-
class
gd.api.
TouchToggleMode
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing toggle modes of a touch trigger.
-
class
gd.api.
TriggerType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing IDs of most triggers.
-
class
gd.api.
ZLayer
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing Z Layer of objects.
-
class
gd.api.
MiscType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing miscellaneous IDs of objects.
-
class
gd.api.
Gamemode
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing different game modes.
-
class
gd.api.
LevelType
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration that represents type of the level.
-
class
gd.api.
Speed
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing speed modifier modes.
-
class
gd.api.
SpeedConstant
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing actual speed modifiers.
-
class
gd.api.
SpeedMagic
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration with magic speed constants.
Magic constants are used for translating distance travelled (in units) with certain speed to time taken, like so:
speed = SpeedMagic.FAST.value # * 2 speed (well, actually just 1.1 lol) x1 = 0 # beginning of the level x2 = 1000 # some random coordinate dx = x2 - x1 t = dx / speed # ~ 2.58 print(t)
-
class
gd.api.
GuidelinesColor
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing guidelines colors.
-
class
gd.api.
LevelDataEnum
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing different fields in level data in save.
-
class
gd.api.
LevelHeaderEnum
(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶ An enumeration representing fields of a level header.
Guidelines¶
Header¶
-
class
gd.api.
Header
(**properties)[source]¶ -
-
background_color
¶ Property (Background Color).
- Type
-
color_1
¶ Property (Color 1).
- Type
-
color_2
¶ Property (Color 2).
- Type
-
color_3
¶ Property (Color 3).
- Type
-
color_3dl
¶ Property (Color 3Dl).
- Type
-
color_4
¶ Property (Color 4).
- Type
-
ground_color
¶ Property (Ground Color).
- Type
-
line_color
¶ Property (Line Color).
- Type
-
object_color
¶ Property (Object Color).
- Type
-
LevelAPI¶
-
class
gd.api.
LevelAPI
(**properties)[source]¶ -
attempts
¶ Property (Attempts).
- Type
WIP
-
binary_version
¶ Property (Binary Version).
- Type
WIP
-
build_tab
¶ Property (Build Tab).
- Type
WIP
-
build_tab_page
¶ Property (Build Tab Page).
- Type
WIP
-
build_tab_pages_dict
¶ Property (Build Tab Pages Dict).
- Type
WIP
-
creator
¶ Property (Creator).
- Type
WIP
-
custom_song
¶ Property (Custom Song).
- Type
WIP
-
description
¶ Property (Description).
- Type
WIP
-
downloads
¶ Property (Downloads).
- Type
WIP
-
editor_layer
¶ Property (Editor Layer).
- Type
WIP
-
extra
¶ Property (Extra).
- Type
WIP
-
first_coin_acquired
¶ Property (First Coin Acquired).
- Type
WIP
-
folder
¶ Property (Folder).
- Type
WIP
-
id
¶ Property (Id).
- Type
WIP
-
info
¶ Property (Info).
- Type
WIP
-
jumps
¶ Property (Jumps).
- Type
WIP
-
kcek
¶ Property (Kcek).
- Type
WIP
-
length
¶ Property (Length).
- Type
WIP
-
level_string
¶ Property (Level String).
- Type
WIP
-
level_type
¶ Property (Level Type).
- Type
WIP
-
likes
¶ Property (Likes).
- Type
WIP
-
name
¶ Property (Name).
- Type
WIP
-
normal_mode_percentage
¶ Property (Normal Mode Percentage).
- Type
WIP
-
objects
¶ Property (Objects).
- Type
WIP
-
official_song
¶ Property (Official Song).
- Type
WIP
-
original
¶ Property (Original).
- Type
WIP
-
password
¶ Property (Password).
- Type
WIP
-
practice_mode_percentage
¶ Property (Practice Mode Percentage).
- Type
WIP
-
requested_stars
¶ Property (Requested Stars).
- Type
WIP
-
revision
¶ Property (Revision).
- Type
WIP
-
second_coin_acquired
¶ Property (Second Coin Acquired).
- Type
WIP
-
seconds_spent_in_editor
¶ Property (Seconds Spent In Editor).
- Type
WIP
-
stars
¶ Property (Stars).
- Type
WIP
-
third_coin_acquired
¶ Property (Third Coin Acquired).
- Type
WIP
-
timely_id
¶ Property (Timely Id).
- Type
WIP
-
unlisted
¶ Property (Unlisted).
- Type
WIP
-
uploaded
¶ Property (Uploaded).
- Type
WIP
-
verified
¶ Property (Verified).
- Type
WIP
-
version
¶ Property (Version).
- Type
WIP
-
x
¶ Property (X).
- Type
WIP
-
y
¶ Property (Y).
- Type
WIP
-
zoom
¶ Property (Zoom).
- Type
WIP
-
HSV¶
-
class
gd.api.
HSV
(h: int = 0, s: float = 1, v: float = 1, s_checked: bool = False, v_checked: bool = False)[source]¶ 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 ons_checked
.v (
float
) – Value (Brightness) float value in range [0, 2] or [-1, 1] depending onv_checked
.s_checked (
bool
) – Whethers
is checked.v_checked (
bool
) – Whetherv
is checked.
ColorChannel¶
Object¶
-
class
gd.api.
Object
(**properties)[source]¶ -
set_id
(directive: str) → gd.api.struct.Object[source]¶ Set
id
ofself
according to the directive, e.g.trigger:move
.
-
set_z_layer
(directive: str) → gd.api.struct.Object[source]¶ Set
z_layer
ofself
according to the directive, e.g.layer:t1
orb3
.
-
set_easing
(directive: str) → gd.api.struct.Object[source]¶ Set
easing
ofself
according to the directive, e.g.sine_in_out
.
-
get_pos
() → Tuple[Union[float, int], Union[float, int]][source]¶ Tuple[Union[
float
,int
], Union[float
,int
]]:x
andy
coordinates ofself
.
-
set_pos
(x: Union[float, int], y: Union[float, int]) → gd.api.struct.Object[source]¶ Set
x
andy
position ofself
to given values.
-
move
(x: Union[float, int] = 0, y: Union[float, int] = 0) → gd.api.struct.Object[source]¶ Add
x
andy
to coordinates ofself
.
-
comparison
¶ Property (Comparison).
-
pickup_mode
¶ Property (Pickup Mode).
- Type
-
target_pos_coordinates
¶ Property (Target Pos Coordinates).
- Type
-
toggle_mode
¶ Property (Toggle Mode).
- Type
-