Levels¶

Main atoms of Geometry Dash are levels; gd.py allows searching, interacting with, modifying and uploading them.

Here is an example of commenting a level:

client = gd.Client()

await client.login('username', 'password')

level = await client.get_level(30029017)

await level.comment('gd.py test comment')

Level¶

class gd.Level(*, client: Optional[Client] = None, **options)[source]¶

Class that represents a Geometry Dash Level. This class is derived from AbstractEntity.

x == y: Check if two objects are equal. Compared by hash and type.

x != y: Check if two objects are not equal.

str(x): Return name of the level.

repr(x): Return representation of the level, useful for debugging.

hash(x): Returns hash(self.hash_str).

to_dict() → Dict[str, Any][source]¶: Convert the entity to a dictionary.

classmethod from_model(model: gd.model.LevelModel, *, client: Optional[Client] = None, creator: Optional[gd.user.User] = None, song: Optional[gd.song.Song] = None, type: Optional[gd.enums.TimelyType] = None, timely_id: int = 0, cooldown: int = - 1) → Level [source]¶: Create new entity from given model, args and kwargs.

classmethod official(id: Optional[int] = None, name: Optional[str] = None, index: Optional[int] = None, client: Optional[Client] = None, get_data: bool = True, server_style: bool = False) → Level [source]¶

Get official level to work with.

Lookup is done in the following form: id -> name -> index.

Parameters

id (Optional[int]) – ID of the official level.
name (Optional[str]) – Name of the official level.
index (Optional[int]) – Index (position) of the official level.
client (Optional[Client]) – Client to attach to the level.
get_data (bool) – Whether to attach data to the level. Default is True.
server_style (bool) – Indicates if server-style of official song ID should be used. Set this to True in case of uploading level to the server. Defaults to False.

Raises

ValueError – No queries were given.
LookupError – Level was not found.

Returns

Official level that was found.

Return type

Level

property name¶

The name of the level.

Type: str

property description¶

Description of the level.

Type: str

property version¶

Version of the level.

Type: int

property downloads¶

Amount of the level’s downloads.

Type: int

property rating¶

Amount of the level’s likes or dislikes.

Type: int

property score¶

Level’s featured score.

Type: int

property creator¶

Creator of the level.

Type: User

property song¶

Song used in the level.

Type: Song

property difficulty¶

Difficulty of the level.

Type: Union[LevelDifficulty, DemonDifficulty]

property password¶

The password to copy the level. See is_copyable().

Type: Optional[int]

is_copyable() → bool [source]¶: bool: Indicates whether a level is copyable.

property stars¶

Amount of stars the level has.

Type: int

property coins¶

Amount of coins in the level.

Type: int

property original_id¶

ID of the original level. (0 if is not a copy)

Type: int

property uploaded_at¶: Optional[datetime]: Timestamp representing when the level was uploaded.

property updated_at¶: Optional[datetime]: Timestamp representing when the level was last updated.

property last_updated_at¶: Optional[datetime]: Timestamp representing when the level was last updated.

property length¶

A type that represents length of the level.

Type: LevelLength

property game_version¶

A version of the game required to play the level.

Type: int

property requested_stars¶

Amount of stars creator of the level has requested.

Type: int

property objects¶

Amount of objects the level has in data.

Type: int

property object_count¶

Amount of objects the level according to the servers.

Type: int

property type¶

A type that shows whether a level is Daily/Weekly.

Type: TimelyType

property timely_id¶

A number that represents current ID of the timely. Increments on new dailies/weeklies. If not timely, equals -1.

Type: int

property cooldown¶

Represents a cooldown until next timely. If not timely, equals -1.

Type: int

is_timely(timely_type: Optional[Union[int, str, gd.enums.TimelyType]] = None) → bool [source]¶: bool: Indicates whether a level is timely/daily/weekly.

is_current_timely(timely_type: Optional[Union[int, str, gd.enums.TimelyType]] = None) → bool [source]¶: bool: Indicates whether a level is current timely/daily/weekly level.

is_rated() → bool [source]¶: bool: Indicates if a level is rated (has stars).

was_unfeatured() → bool [source]¶: bool: Indicates if a level was featured, but got unfeatured.

is_featured() → bool [source]¶: bool: Indicates whether a level is featured.

is_epic() → bool [source]¶: bool: Indicates whether a level is epic.

is_demon() → bool [source]¶: bool: Indicates whether a level is demon.

is_auto() → bool [source]¶: bool: Indicates whether a level is auto.

is_original() → bool [source]¶: bool: Indicates whether a level is original.

has_coins_verified() → bool [source]¶: bool: Indicates whether level’s coins are verified.

async report() → None [source]¶

Reports a level.

Raises

MissingAccess – Failed to report a level.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async upload(**kwargs) → None [source]¶

Upload self.

Parameters

**kwargs – Arguments that upload_level() accepts. Defaults are properties of the level.

Raises

MissingAccess – Failed to upload the level.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async delete() → None [source]¶

Deletes a level.

Raises

MissingAccess – Failed to delete a level.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async update_description(content: str) → None [source]¶

Updates level description.

Parameters

content (str) – Content of the new description. If None or omitted, nothing is run.

Raises

MissingAccess – Failed to update level’s description.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async rate(stars: int) → None [source]¶

Sends level rating.

Parameters: stars (int) – Amount of stars to rate with.
Raises: MissingAccess – Failed to rate a level.

async rate_demon(demon_difficulty: Union[int, str, gd.enums.DemonDifficulty], as_mod: bool = False) → None [source]¶

Sends level demon rating.

Parameters

demon_difficulty (Union[int, str, DemonDifficulty]) – Demon difficulty to rate a level with.
as_mod (bool) – Whether to send a demon rating as moderator.

Raises

MissingAccess – If attempted to rate a level as moderator without required permissions.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async send(stars: int, featured: bool) → None [source]¶

Sends a level to Geometry Dash Developer and Administrator, RobTop.

Parameters

stars (int) – Amount of stars to send with.
featured (bool) – Whether to send for a feature, or for a rate.

Raises

MissingAccess – Missing required moderator permissions.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async is_alive() → bool [source]¶

Checks if a level is still on Geometry Dash servers.

Returns: True if a level is still alive, and False otherwise. Also False if a client is not attached to the level.
Return type: bool

async update(*, get_data: bool = True) → Optional[gd.level.Level][source]¶

Refreshes a level. Returns None on fail.

Note

This function actually refreshes a level and its stats. No need to do funky stuff with its return.

Returns: A newly fetched version. None if failed to fetch.
Return type: Level

async refresh(*, get_data: bool = True) → Optional[gd.level.Level]¶

Refreshes a level. Returns None on fail.

Note

This function actually refreshes a level and its stats. No need to do funky stuff with its return.

Returns: A newly fetched version. None if failed to fetch.
Return type: Level

async comment(content: str, percent: int = 0) → Optional[Comment][source]¶

Posts a comment on a level.

Parameters

content (str) – Body of the comment to post.
percent (int) –
Percentage to display. Default is 0.

Note

gd.py developers are not responsible for effects that changing this may cause. Set this parameter higher than 0 on your own risk.

Raises

MissingAccess – Failed to post a level comment.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

Returns

Sent comment.

Return type

Optional[Comment]

async like() → None [source]¶

Likes a level.

Raises

MissingAccess – Failed to like a level.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async dislike() → None [source]¶

Dislikes a level.

Raises

MissingAccess – Failed to dislike a level.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

get_leaderboard(strategy: Union[int, str, gd.enums.LevelLeaderboardStrategy] = <LevelLeaderboardStrategy.ALL: 1>) → AsyncIterator[gd.user.User][source]¶

Retrieves the leaderboard of a level.

Parameters

strategy (Union[int, str, LevelLeaderboardStrategy]) – Strategy to apply when fetching.

Raises

MissingAccess – Failed to get leaderboard of the level.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

Returns

A list of users.

Return type

AsyncIterator[User]

get_comments(strategy: Union[int, str, gd.enums.CommentStrategy] = <CommentStrategy.RECENT: 0>, pages: Iterable[int] = (0, ), amount: int = 20, concurrent: bool = True) → AsyncIterator[Comment][source]¶

Retrieves level comments.

Parameters

strategy (Union[int, str, CommentStrategy]) – A strategy to apply when searching.
pages (Iterable[int]) – Pages to search at. By default, only page 0.
amount (int) – Amount of comments to retrieve. Default is 20. For amount < 0, 1 << 31 is added, allowing to fetch a theoretical limit of comments.
concurrent (bool) – Whether to fetch pages concurrently. True by default.

Returns

Comments retrieved.

Return type

AsyncIterator[Comment]

Raises

MissingAccess – Failed to fetch comments.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

get_comments_on_page(strategy: Union[int, str, gd.enums.CommentStrategy] = <CommentStrategy.RECENT: 0>, page: int = 0, amount: int = 20) → AsyncIterator[Comment][source]¶

Retrieves level comments.

Parameters

strategy (Union[int, str, CommentStrategy]) – A strategy to apply when searching.
amount (int) – Amount of comments to retrieve. Default is 20. For amount < 0, 1 << 31 is added, allowing to fetch a theoretical limit of comments.

Returns

Comments retrieved.

Return type

AsyncIterator[Comment]

Raises

MissingAccess – Failed to fetch comments.
NothingFound – No comments were found.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

attach_client(client: Optional[Client] = None) → AbstractEntityT¶

Attach client to self.

Parameters: client (Optional[gd.Client]) – Client to attach. If None or not given, will be detached.
Returns: This abstract entity.
Return type: AbstractEntity

property client¶

Client attached to this object. This checks if client is not present, and raises ClientException in that case.

Type: Client

property client_unchecked¶

Client attached to this object.

Type: Optional[Client]

detach_client() → AbstractEntityT¶

Detach client from self.

Same as calling:

self.attach_client(None)

Returns: This abstract entity.
Return type: AbstractEntity

classmethod from_dict(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_dicts(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_models(*models: gd.model_backend.Model, **kwargs) → AbstractEntityT¶: Create new entity from given models by calling from_model with kwargs.

property hash_str¶

String used for hashing, with format <Class(ID->id)>.

Type: str

property id¶

ID of the Entity.

Type: int

update_inner(**options: Any) → AbstractEntityT¶: Update self.options with options.

Difficulty¶

gd.get_actual_difficulty(level_difficulty: int, demon_difficulty: int, is_auto: bool, is_demon: bool) → Union[gd.enums.LevelDifficulty, gd.enums.DemonDifficulty][source]¶

Get real level difficulty from given parameters.

Parameters

level_difficulty (int) – Number that represents level difficulty.
demon_difficulty (int) – Number that represents level demon difficulty.
is_auto (bool) – Whether the level is auto.
is_demon (bool) – Whether the level is demon.

Returns

Level or demon difficulty, based on parameters.

Return type

Union[LevelDifficulty, DemonDifficulty]

Password¶

class gd.Password(password: Optional[Union[int, str]] = None, copyable: bool = True)[source]¶

Class that represents passwords.

str(x): Return a human-friendly description of the password. For example, copyable, password 101010.

repr(x): Return representation of the password, useful for debugging.

Parameters

password (Optional[Union[int, str]]) – Actual password, as a number or a string.
copyable (bool) – Whether passwords implies that something is copyable. If True and password is None, free copy is assumed.

property copyable¶

Whether password implies that something is copyable.

Type: bool

property password¶

Actual password, None if not given.

Type: Optional[int]

classmethod from_robtop_number(number: int) → gd.converters.Password[source]¶: Create Password from number.

to_robtop_number() → int [source]¶: Convert Password to a number.

classmethod from_robtop(string: str) → gd.converters.Password[source]¶: Same as from_robtop_number(), except it attempts decoding.

to_robtop(encode: bool = True) → str [source]¶: Same as to_robtop_number(), except it optionally applies encoding.

Searching¶

gd.py also provides a convenient way of searching for different levels:

client = gd.Client()

async for level in client.search_levels("Bloodlust"):
    print(level.name)

# also by filters!

async for level in client.search_levels(filters=gd.Filters.with_song(1, custom=False)):
    print(level.rating)

Filters¶

class gd.Filters(strategy: Union[int, str, gd.enums.SearchStrategy] = <SearchStrategy.REGULAR: 0>, difficulty: Optional[Union[Iterable[Union[int, str, gd.enums.LevelDifficulty]], int, str, gd.enums.LevelDifficulty]] = None, demon_difficulty: Optional[Union[int, str, gd.enums.DemonDifficulty]] = None, length: Optional[Union[int, str, gd.enums.LevelLength]] = None, not_completed: bool = False, only_completed: bool = False, completed_levels: Iterable[Union[int, Level]] = (), require_coins: bool = False, featured: bool = False, epic: bool = False, rated: Optional[bool] = None, require_two_player: bool = False, song_id: Optional[int] = None, use_custom_song: bool = False, require_original: bool = False, followed: Iterable[Union[int, User]] = ())[source]¶: Class that adds ability to create custom filters to apply when searching for levels.

Geometry Dash has different level packs to play; currently, there are two of those: Map Packs and Gauntlets.

Here is an example of fetching levels of a Fire gauntlet:

client = gd.Client()

fire_gauntlet = await client.get_gauntlets().get(name="Fire Gauntlet")

for level in await fire_gauntlet.get_levels():
    print(level.id, level.rating, level.name)

Level Packs¶

class gd.MapPack(*, client: Optional[Client] = None, **options)[source]¶

Class that represents Map Pack in Geometry Dash. This class is derived from Gauntlet.

x == y: Check if two objects are equal. Compared by hash and type.

x != y: Check if two objects are not equal.

str(x): Return name of the map pack.

repr(x): Return representation of the map pack, useful for debugging.

hash(x): Returns hash(self.hash_str).

classmethod from_model(model: gd.model.MapPackModel, *, client: Optional[Client] = None) → MapPack [source]¶: Create new entity from given model, args and kwargs.

property stars¶

Amount of stars this map pack has.

Type: int

property coins¶

Number of coins this map pack grants on completion.

Type: int

property difficulty¶

Average difficulty of a map pack.

Type: LevelDifficulty

property color¶

Color of a map pack.

Type: Color

property other_color¶

Other color of a map pack.

Type: Color

attach_client(client: Optional[Client] = None) → AbstractEntityT¶

Attach client to self.

Parameters: client (Optional[gd.Client]) – Client to attach. If None or not given, will be detached.
Returns: This abstract entity.
Return type: AbstractEntity

property client¶

Client attached to this object. This checks if client is not present, and raises ClientException in that case.

Type: Client

property client_unchecked¶

Client attached to this object.

Type: Optional[Client]

detach_client() → AbstractEntityT¶

Detach client from self.

Same as calling:

self.attach_client(None)

Returns: This abstract entity.
Return type: AbstractEntity

classmethod from_dict(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_dicts(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_models(*models: gd.model_backend.Model, **kwargs) → AbstractEntityT¶: Create new entity from given models by calling from_model with kwargs.

get_levels() → AsyncIterator[Level]¶

Retrieves levels of a Level Pack. Also updates inner levels attribute.

Returns: Levels that are found.
Return type: AsyncIterator[Level]

property hash_str¶

String used for hashing, with format <Class(ID->id)>.

Type: str

property id¶

ID of the Entity.

Type: int

property level_ids¶

Tuple of level IDs that are contained in the gauntlet.

Type: Tuple[int]

property levels¶

Tuple containing levels of the Gauntlet.

Can be retrieved with get_levels().

Type: Tuple[Level]

property name¶

Name of the Gauntlet.

Type: str

to_dict() → Dict[str, Any]¶: Convert the entity to a dictionary.

update_inner(**options: Any) → AbstractEntityT¶: Update self.options with options.

class gd.Gauntlet(*, client: Optional[Client] = None, **options)[source]¶

Class that represents The Lost Gauntlet in Geometry Dash. This class is derived from AbstractEntity.

x == y: Check if two objects are equal. Compared by hash and type.

x != y: Check if two objects are not equal.

str(x): Return name of the gauntlet.

repr(x): Return representation of the gauntlet, useful for debugging.

hash(x): Returns hash(self.hash_str).

to_dict() → Dict[str, Any][source]¶: Convert the entity to a dictionary.

classmethod from_model(model: gd.model.GauntletModel, *, client: Optional[Client] = None) → Gauntlet [source]¶: Create new entity from given model, args and kwargs.

property name¶

Name of the Gauntlet.

Type: str

property level_ids¶

Tuple of level IDs that are contained in the gauntlet.

Type: Tuple[int]

property levels¶

Tuple containing levels of the Gauntlet.

Can be retrieved with get_levels().

Type: Tuple[Level]

get_levels() → AsyncIterator[Level][source]¶

Retrieves levels of a Level Pack. Also updates inner levels attribute.

Returns: Levels that are found.
Return type: AsyncIterator[Level]

attach_client(client: Optional[Client] = None) → AbstractEntityT¶

Attach client to self.

Parameters: client (Optional[gd.Client]) – Client to attach. If None or not given, will be detached.
Returns: This abstract entity.
Return type: AbstractEntity

property client¶

Client attached to this object. This checks if client is not present, and raises ClientException in that case.

Type: Client

property client_unchecked¶

Client attached to this object.

Type: Optional[Client]

detach_client() → AbstractEntityT¶

Detach client from self.

Same as calling:

self.attach_client(None)

Returns: This abstract entity.
Return type: AbstractEntity

classmethod from_dict(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_dicts(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_models(*models: gd.model_backend.Model, **kwargs) → AbstractEntityT¶: Create new entity from given models by calling from_model with kwargs.

property hash_str¶

String used for hashing, with format <Class(ID->id)>.

Type: str

property id¶

ID of the Entity.

Type: int

update_inner(**options: Any) → AbstractEntityT¶: Update self.options with options.