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: gd.client.Client = None, **options)[source]¶

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

classmethod official(id: Optional[int] = None, name: Optional[str] = None, index: Optional[int] = None, client: Optional[gd.client.Client] = None, get_data: bool = True, server_style: bool = False) → gd.level.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

name¶

The name of the level.

Type: str

description¶

Description of the level.

Type: str

version¶

Version of the level.

Type: int

downloads¶

Amount of the level’s downloads.

Type: int

rating¶

Amount of the level’s likes or dislikes.

Type: int

score¶

Level’s featured score.

Type: int

creator¶

Creator of the level.

Type: AbstractUser

song¶

Song used in the level.

Type: Song

difficulty¶

Difficulty of the level.

Type: Union[LevelDifficulty, DemonDifficulty]

password¶

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

Type: Optional[int]

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

stars¶

Amount of stars the level has.

Type: int

coins¶

Amount of coins in the level.

Type: int

original_id¶

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

Type: int

uploaded_timestamp¶

A human-readable string representing how much time ago level was uploaded.

Type: str

last_updated_timestamp¶

A human-readable string showing how much time ago the last update was.

Type: str

length¶

A type that represents length of the level.

Type: LevelLength

game_version¶

A version of the game required to play the level.

Type: int

requested_stars¶

Amount of stars creator of the level has requested.

Type: int

objects¶

Amount of objects the level has in data.

Type: int

object_count¶

Amount of objects the level according to the servers.

Type: int

type¶

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

Type: TimelyType

timely_index¶

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

Type: int

cooldown¶

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

Type: int

data¶

Level data, represented as a stream.

Type: Union[str, bytes]

is_timely(daily_or_weekly: Optional[str] = None) → bool [source]¶: bool: Indicates whether a level is timely/daily/weekly. For instance, let’s suppose a level is daily. Then, the behavior of this method is: level.is_timely() -> True and level.is_timely('daily') -> True but level.is_timely('weekly') -> False.

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.

download() → Union[bytes, str][source]¶: Union[str, bytes]: Returns level data, represented as string.

await report() → None [source]¶

This function is a coroutine.

Reports a level.

Raises: MissingAccess – Failed to report a level.

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

This function is a coroutine.

Upload self.

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

await delete() → None [source]¶

This function is a coroutine.

Deletes a level.

Raises: MissingAccess – Failed to delete a level.

await update_description(content: Optional[str] = None) → None [source]¶

This function is a coroutine.

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.

await rate(stars: int = 1) → None [source]¶

This function is a coroutine.

Sends level rating.

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

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

This function is a coroutine.

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.

await send(stars: int = 1, featured: bool = True) → None [source]¶

This function is a coroutine.

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

Parameters

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

Raises

MissingAccess – Missing required moderator permissions.

await is_alive() → bool [source]¶

This function is a coroutine.

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.s
Return type: bool

await refresh() → Optional[gd.level.Level][source]¶

This function is a coroutine.

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

await comment(content: str, percentage: int = 0) → Optional[gd.comment.Comment][source]¶

This function is a coroutine.

Posts a comment on a level.

Parameters

content (str) – Body of the comment to post.
percentage (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.

Returns

Sent comment.

Return type

Optional[Comment]

await like() → None [source]¶

This function is a coroutine.

Likes a level.

Raises: MissingAccess – Failed to like a level.

await dislike() → None [source]¶

This function is a coroutine.

Dislikes a level.

Raises: MissingAccess – Failed to dislike a level.

await get_leaderboard(strategy: Union[int, str, gd.utils.enums.LevelLeaderboardStrategy] = 0) → List[gd.abstractuser.LevelRecord][source]¶

This function is a coroutine.

Retrieves the leaderboard of a level.

Parameters: strategy (Union[int, str, LevelLeaderboardStrategy]) – A strategy to apply.
Returns: A list of user-like objects.
Return type: List[LevelRecord]

await get_comments(strategy: Union[int, str, gd.utils.enums.CommentStrategy] = 0, amount: int = 20, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.comment.Comment][source]¶

This function is a coroutine.

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, 2 ** 31 is added, allowing to fetch a theoretical limit of comments.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

List of comments retrieved.

Return type

List[Comment]

Raises

MissingAccess – Failed to fetch comments.
NothingFound – No comments were found.

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

client = gd.Client()

for level in await client.search_levels('Bloodlust'):
    print(level.name)

# also by filters!

for level in await client.search_levels(filters=gd.Filters.setup_with_song(1)):
    print(level.rating)

Filters¶

class gd.Filters(strategy: Union[int, str, gd.utils.enums.SearchStrategy] = 0, difficulty: Optional[Sequence[Union[int, str, gd.utils.enums.LevelDifficulty]]] = None, demon_difficulty: Optional[Union[int, str, gd.utils.enums.DemonDifficulty]] = None, length: Optional[Union[int, str, gd.utils.enums.LevelLength]] = None, uncompleted: bool = False, only_completed: bool = False, completed_levels: Optional[Sequence[Union[int, gd.level.Level]]] = None, 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: Optional[Sequence[Union[int, gd.abstractuser.AbstractUser]]] = None)[source]¶

Class that adds ability to create custom filters to apply when searching for levels.

strategy¶

A strategy to apply.

Type: Optional[Union[int, str, SearchStrategy]]

difficulty¶

Level difficulties to apply. Either sequence of many or just one difficulty.

Type: Optional[Sequence[Union[int, str, LevelDifficulty]]]

demon_difficulty¶

One Demon difficulty to apply as a filter.

Type: Optional[Union[int, str, DemonDifficulty]]

length¶

Same as difficulty, but for lengths.

Type: Sequence[Union[int, str, LevelLength]]

uncompleted¶

Whether to search for uncompleted levels only. If true, completed_levels is required.

Type: Optional[bool]

only_completed¶

Opposite of uncompleted.

Type: Optional[bool]

completed_levels¶

A sequence of completed levels.

Type: Optional[Sequence[Union[int, Level]]]

require_coins¶

Whether levels must have coins in them.

Type: Optional[bool]

featured¶

Whether levels must be featured.

Type: Optional[bool]

epic¶

Whether levels ought to be epic.

Type: Optional[bool]

rated¶

This defaults to None. If true, will search for only rated levels, if false, will search for only not rated levels. If None, makes no changes.

Type: Optional[bool]

require_two_player¶

Whether a level must be for two players.

Type: Optional[bool]

song_id¶

An ID of the song that should be used.

Type: Optional[int]

use_custom_song¶

Whether a custom song should be used. Requires song_id to be defined.

Type: Optional[int]

require_original¶

Whether levels must be original.

Type: Optional[bool]

followed¶

Followed users, basically this will work as BY_USER strategy, but for many users.

Type: Optional[Sequence[Union[int, AbstractUser, User]]]

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

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

client = gd.Client()

gauntlets = await client.get_gauntlets()

fire_gauntlet = gd.utils.get(gauntlets, name='Fire Gauntlet')

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

Level Packs¶

class gd.MapPack(**options)[source]¶

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

stars¶

Amount of stars this map pack has.

Type: int

coins¶

Number of coins this map pack grants on completion.

Type: int

difficulty¶

Average difficulty of a map pack.

Type: LevelDifficulty

color¶

Color of a map pack.

Type: Color

class gd.Gauntlet(**options)[source]¶

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

name¶

Name of the Gauntlet.

Type: str

level_ids¶

Tuple of level IDs that are contained in the gauntlet.

Type: Tuple[int]

levels¶

Tuple containing levels of the Gauntlet.

Can be retrieved with Gauntlet.get_levels().

Type: Tuple[Level]

await get_levels() → List[gd.level.Level][source]¶

This function is a coroutine.

Retrieves levels of a Gauntlet or its subclass.

Returns: List of levels that are found.
Return type: List[Level]