gdformat 0.1.0__tar.gz

gdformat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RealistikDash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gdformat-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: gdformat
+Version: 0.1.0
+Summary: Parser and builder for the Geometry Dash 2.2 server protocol.
+Keywords: geometry-dash,gdps,gd,protocol,parser,serialisation
+Author: RealistikDash
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Maintainer: RealistikDash
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/RealistikGDPS/gdformat
+Project-URL: Repository, https://github.com/RealistikGDPS/gdformat
+Project-URL: Issues, https://github.com/RealistikGDPS/gdformat/issues
+Description-Content-Type: text/markdown
+
+# gdformat
+
+Parser and builder for the Geometry Dash 2.2 server protocol. It covers the
+wire objects, the full endpoint response envelopes and typed parsing of every
+endpoint's form parameters, so a server never handles the raw format itself.
+
+Only the latest game version is supported. Python 3.14, managed with uv, no
+runtime dependencies.
+
+## Layout
+
+| Module | Contents |
+|--------|----------|
+| `gdformat.objects` | Frozen dataclasses for each wire object (`Level`, `User`, `Comment`, `Song`, ...) with `serialise_*` / `parse_*` functions. |
+| `gdformat.responses` | One `serialise_*` per endpoint response, producing the exact string to send. |
+| `gdformat.requests` | One `*Request` dataclass and `parse_*` per endpoint, taking the POST form. `verify_*` helpers check the client integrity values. |
+| `gdformat.crypto` | XOR keys and salts, `gjp2`, `chk` generation, response hashes, level passwords, leaderboard seeds. |
+| `gdformat.encoding` | Base64, XOR, level string compression, URL quoting, relative age strings. |
+| `gdformat.enums` | Every discriminant the protocol uses. |
+| `gdformat.codes` | Documented numeric response codes. |
+
+## Usage
+
+```python
+from gdformat import is_error, objects, requests, responses
+
+def download_level(form: dict[str, str]) -> str:
+    request = requests.parse_download_level(form)
+    if is_error(request):
+        return "-1"
+
+    level = objects.Level(...)  # Built from your storage.
+    return responses.serialise_level_download(level, songs)
+```
+
+Failures are values: every parser returns `T | ParseError`, narrowed with
+`is_error` / `is_success`. Nothing in the library raises.

gdformat-0.1.0/README.md

@@ -0,0 +1,37 @@
+# gdformat
+
+Parser and builder for the Geometry Dash 2.2 server protocol. It covers the
+wire objects, the full endpoint response envelopes and typed parsing of every
+endpoint's form parameters, so a server never handles the raw format itself.
+
+Only the latest game version is supported. Python 3.14, managed with uv, no
+runtime dependencies.
+
+## Layout
+
+| Module | Contents |
+|--------|----------|
+| `gdformat.objects` | Frozen dataclasses for each wire object (`Level`, `User`, `Comment`, `Song`, ...) with `serialise_*` / `parse_*` functions. |
+| `gdformat.responses` | One `serialise_*` per endpoint response, producing the exact string to send. |
+| `gdformat.requests` | One `*Request` dataclass and `parse_*` per endpoint, taking the POST form. `verify_*` helpers check the client integrity values. |
+| `gdformat.crypto` | XOR keys and salts, `gjp2`, `chk` generation, response hashes, level passwords, leaderboard seeds. |
+| `gdformat.encoding` | Base64, XOR, level string compression, URL quoting, relative age strings. |
+| `gdformat.enums` | Every discriminant the protocol uses. |
+| `gdformat.codes` | Documented numeric response codes. |
+
+## Usage
+
+```python
+from gdformat import is_error, objects, requests, responses
+
+def download_level(form: dict[str, str]) -> str:
+    request = requests.parse_download_level(form)
+    if is_error(request):
+        return "-1"
+
+    level = objects.Level(...)  # Built from your storage.
+    return responses.serialise_level_download(level, songs)
+```
+
+Failures are values: every parser returns `T | ParseError`, narrowed with
+`is_error` / `is_success`. Nothing in the library raises.

gdformat-0.1.0/gdformat/__init__.py

@@ -0,0 +1,12 @@
+from . import codes
+from . import crypto
+from . import encoding
+from . import enums
+from . import objects
+from . import requests
+from . import responses
+from ._common import Form
+from ._common import ParseError
+from ._common import ParseResult
+from ._common import is_error
+from ._common import is_success

gdformat-0.1.0/gdformat/_common.py

@@ -0,0 +1,24 @@
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import TypeIs
+
+type Form = Mapping[str, str]
+
+
+class ParseError(StrEnum):
+    MISSING = "missing"
+    INVALID_INTEGER = "invalid_integer"
+    INVALID_VALUE = "invalid_value"
+    INVALID_BASE64 = "invalid_base64"
+    INVALID_LAYOUT = "invalid_layout"
+
+
+type ParseResult[T] = T | ParseError
+
+
+def is_error[T](value: ParseResult[T]) -> TypeIs[ParseError]:
+    return isinstance(value, ParseError)
+
+
+def is_success[T](value: ParseResult[T]) -> TypeIs[T]:
+    return not isinstance(value, ParseError)

gdformat-0.1.0/gdformat/_wire.py

@@ -0,0 +1,190 @@
+from collections.abc import Mapping
+from enum import IntEnum
+from enum import StrEnum
+
+from gdformat._common import ParseError
+from gdformat._common import ParseResult
+from gdformat.encoding import decode_text
+
+
+def pairs(text: str, separator: str) -> dict[str, str] | None:
+    parts = text.split(separator)
+
+    if len(parts) % 2:
+        return None
+
+    return dict(zip(parts[::2], parts[1::2], strict=True))
+
+
+def split_nonempty(text: str, separator: str) -> list[str]:
+    return [part for part in text.split(separator) if part]
+
+
+class Reader:
+    """Reads typed values out of a string mapping, remembering the first failure.
+    Failed reads return a placeholder so callers can build the whole model in one
+    expression and then check `done`."""
+
+    __slots__ = ("_values", "error")  # One instance per parsed request or object.
+
+    def __init__(self, values: Mapping[str, str]) -> None:
+        self._values = values
+        self.error: ParseError | None = None
+
+    def _fail(self, error: ParseError) -> None:
+        if self.error is None:
+            self.error = error
+
+    def _to_int(self, value: str) -> int:
+        try:
+            return int(value)
+        except ValueError:
+            self._fail(ParseError.INVALID_INTEGER)
+
+            return 0
+
+    def has(self, key: str) -> bool:
+        return bool(self._values.get(key))
+
+    def string(self, key: str, *, default: str | None = None) -> str:
+        value = self._values.get(key)
+
+        if value is not None:
+            return value
+
+        if default is None:
+            self._fail(ParseError.MISSING)
+
+            return ""
+
+        return default
+
+    def integer(self, key: str, *, default: int | None = None) -> int:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return 0
+
+            return default
+
+        return self._to_int(value)
+
+    def optional_integer(self, key: str) -> int | None:
+        value = self._values.get(key)
+
+        if not value:
+            return None
+
+        return self._to_int(value)
+
+    def boolean(self, key: str, *, default: bool = False) -> bool:
+        value = self._values.get(key)
+
+        if not value:
+            return default
+
+        return value == "1"
+
+    def member[E: IntEnum](
+        self, key: str, kind: type[E], *, default: E | None = None
+    ) -> E:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return next(iter(kind))
+
+            return default
+
+        return self._to_member(value, kind)
+
+    def optional_member[E: IntEnum](self, key: str, kind: type[E]) -> E | None:
+        value = self._values.get(key)
+
+        if not value:
+            return None
+
+        return self._to_member(value, kind)
+
+    def _to_member[E: IntEnum](self, value: str, kind: type[E]) -> E:
+        number = self._to_int(value)
+
+        try:
+            return kind(number)
+        except ValueError:
+            self._fail(ParseError.INVALID_VALUE)
+
+            return next(iter(kind))
+
+    def choice[E: StrEnum](
+        self, key: str, kind: type[E], *, default: E | None = None
+    ) -> E:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return next(iter(kind))
+
+            return default
+
+        try:
+            return kind(value)
+        except ValueError:
+            self._fail(ParseError.INVALID_VALUE)
+
+            return next(iter(kind))
+
+    def text(self, key: str, *, default: str | None = None) -> str:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return ""
+
+            return default
+
+        decoded = decode_text(value)
+
+        if decoded is None:
+            self._fail(ParseError.INVALID_BASE64)
+
+            return ""
+
+        return decoded
+
+    def integers(self, key: str, *, separator: str = ",") -> tuple[int, ...]:
+        value = self._values.get(key)
+
+        if not value or value == "-":
+            return ()
+
+        return tuple(
+            self._to_int(part) for part in value.strip("()").split(separator) if part
+        )
+
+    def members[E: IntEnum](
+        self,
+        key: str,
+        kind: type[E],
+        *,
+        separator: str = ",",
+    ) -> tuple[E, ...]:
+        value = self._values.get(key)
+
+        if not value or value == "-":
+            return ()
+
+        return tuple(
+            self._to_member(part, kind) for part in value.split(separator) if part
+        )
+
+    def done[T](self, value: T) -> ParseResult[T]:
+        if self.error is not None:
+            return self.error
+
+        return value

gdformat-0.1.0/gdformat/codes.py

@@ -0,0 +1,59 @@
+from enum import IntEnum
+
+SUCCESS = "1"
+FAILURE = "-1"
+
+
+class LoginError(IntEnum):
+    GENERIC = -1
+    PASSWORD_TOO_SHORT = -8
+    NAME_TOO_SHORT = -9
+    LINKED_TO_OTHER_ACCOUNT = -10
+    WRONG_CREDENTIALS = -11
+    ACCOUNT_DISABLED = -12
+    LINKED_TO_OTHER_STEAM = -13
+
+
+class RegisterError(IntEnum):
+    GENERIC = -1
+    NAME_TAKEN = -2
+    EMAIL_TAKEN = -3
+    NAME_INVALID = -4
+    PASSWORD_INVALID = -5
+    EMAIL_INVALID = -6
+    PASSWORD_TOO_SHORT = -8
+    NAME_TOO_SHORT = -9
+
+
+class SaveError(IntEnum):
+    GENERIC = -1
+    LOGIN_FAILED = -2
+    GENERIC_VISIBLE = -3
+    TOO_LARGE = -4
+    BAD_LOGIN = -5
+    SERVER_ERROR = -6
+
+
+class SongError(IntEnum):
+    NOT_FOUND = -1
+    NOT_ALLOWED = -2
+
+
+class CommentError(IntEnum):
+    REJECTED = -1
+    NONE_FOUND = -2
+    PERMANENT_BAN = -10
+
+
+class ListUploadError(IntEnum):
+    REJECTED = -1
+    BAD_SEED = -10
+
+
+class ModeratorError(IntEnum):
+    REJECTED = -1
+    NOT_MODERATOR = -2
+
+
+def serialise_code(code: int) -> str:
+    return str(int(code))

gdformat-0.1.0/gdformat/crypto.py

@@ -0,0 +1,296 @@
+import hashlib
+from collections.abc import Iterable
+
+from gdformat.encoding import cyclic_xor
+from gdformat.encoding import decode_base64
+from gdformat.encoding import encode_base64
+from gdformat.encoding import encode_xor_text
+
+KEY_MESSAGE = b"14251"
+KEY_VAULT = b"19283"
+KEY_CHALLENGES = b"19847"
+KEY_LEVEL_PASSWORD = b"26364"
+KEY_COMMENT = b"29481"
+KEY_ACCOUNT_PASSWORD = b"37526"
+KEY_LEVEL_LEADERBOARD = b"39673"
+KEY_LEVEL = b"41274"
+KEY_LOAD = b"48291"
+KEY_LIBRARY = b"57709"
+KEY_RATING = b"58281"
+KEY_CHESTS = b"59182"
+KEY_STATS = b"85271"
+
+SALT_LEVEL = "xI25fpAapCQg"
+SALT_COMMENT = "xPT6iUrtws0J"
+SALT_LIKE = "ysg6pUrtjn0J"
+SALT_PROFILE = "xI35fsAapCRg"
+SALT_LEVEL_LEADERBOARD = "yPg6pUrtWn0J"
+SALT_VAULT = "ask2fpcaqCQ2"
+SALT_CHALLENGES = "oC36fpYaPtdg"
+SALT_REWARDS = "pC26fpYaQCtg"
+SALT_GJP2 = "mI29fmAnxgTs"
+
+_SEED_SAMPLE_SIZE = 50
+_DOWNLOAD_SAMPLE_SIZE = 40
+
+
+def sha1_hex(text: str) -> str:
+    return hashlib.sha1(text.encode()).hexdigest()
+
+
+def gjp2(password: str) -> str:
+    return sha1_hex(password + SALT_GJP2)
+
+
+def chk(values: Iterable[object], key: bytes, salt: str) -> str:
+    joined = "".join(map(str, values)) + salt
+
+    return encode_base64(cyclic_xor(sha1_hex(joined).encode(), key))
+
+
+def sample(data: str, count: int) -> str:
+    if len(data) < count:
+        return data
+
+    return data[:: len(data) // count][:count]
+
+
+def comment_chk(
+    username: str,
+    content: str,
+    level_id: int,
+    percent: int,
+    comment_type: int,
+) -> str:
+    """`content` is the URL-safe base64 form of the comment, as sent on the wire."""
+
+    return chk(
+        (username, content, level_id, percent, comment_type), KEY_COMMENT, SALT_COMMENT
+    )
+
+
+def like_chk(
+    special: int,
+    item_id: int,
+    like: bool,
+    like_type: int,
+    rs: str,
+    account_id: int,
+    udid: str,
+    user_id: int,
+) -> str:
+    return chk(
+        (special, item_id, int(like), like_type, rs, account_id, udid, user_id),
+        KEY_RATING,
+        SALT_LIKE,
+    )
+
+
+def rate_chk(
+    level_id: int,
+    stars: int,
+    rs: str,
+    account_id: int,
+    udid: str,
+    user_id: int,
+) -> str:
+    return chk((level_id, stars, rs, account_id, udid, user_id), KEY_RATING, SALT_LIKE)
+
+
+def download_chk(
+    level_id: int,
+    increment: bool,
+    rs: str,
+    account_id: int,
+    udid: str,
+    user_id: int,
+) -> str:
+    # NOTE: The documentation lists no salt for this value; this follows it as written.
+    return chk((level_id, int(increment), rs, account_id, udid, user_id), KEY_LEVEL, "")
+
+
+def profile_chk(values: Iterable[object]) -> str:
+    return chk(values, KEY_STATS, SALT_PROFILE)
+
+
+def level_leaderboard_chk(values: Iterable[object], rs: str) -> str:
+    return chk((*values, SALT_LEVEL_LEADERBOARD, rs), KEY_LEVEL_LEADERBOARD, "")
+
+
+def level_seed(level_string: str) -> str:
+    """The `seed2` parameter of a level upload."""
+
+    sampled = sample(level_string, _SEED_SAMPLE_SIZE)
+
+    return encode_base64(cyclic_xor(sha1_hex(sampled + SALT_LEVEL).encode(), KEY_LEVEL))
+
+
+def list_seed(level_ids: str, account_id: int, seed2: str) -> str:
+    """The `seed` parameter of a list upload; `seed2` is the random key it was
+    encrypted with."""
+
+    sampled = sample(level_ids, _SEED_SAMPLE_SIZE)
+    digest = sha1_hex(f"{sampled}{account_id}")
+
+    return encode_base64(cyclic_xor(digest.encode(), seed2.encode()))
+
+
+def level_download_hash(level_string: str) -> str:
+    if len(level_string) <= _DOWNLOAD_SAMPLE_SIZE:
+        return sha1_hex(level_string + SALT_LEVEL)
+
+    step = len(level_string) // _DOWNLOAD_SAMPLE_SIZE
+
+    sampled = "".join(
+        level_string[index * step] for index in range(_DOWNLOAD_SAMPLE_SIZE)
+    )
+
+    return sha1_hex(sampled + SALT_LEVEL)
+
+
+def level_metadata_hash(
+    creator_id: int,
+    stars: int,
+    is_demon: bool,
+    level_id: int,
+    verified_coins: bool,
+    feature_score: int,
+    password: int,
+    timely_id: int,
+) -> str:
+    joined = (
+        f"{creator_id},{stars},{is_demon:d},{level_id},{verified_coins:d},"
+        f"{feature_score},{password},{timely_id}"
+    )
+
+    return sha1_hex(joined + SALT_LEVEL)
+
+
+def level_search_hash(levels: Iterable[tuple[int, int, bool]]) -> str:
+    """`levels` yields `(level_id, stars, verified_coins)` per level, in order."""
+
+    parts = []
+
+    for level_id, stars, verified_coins in levels:
+        digits = str(level_id)
+        parts.append(f"{digits[0]}{digits[-1]}{stars}{verified_coins:d}")
+
+    return sha1_hex("".join(parts) + SALT_LEVEL)
+
+
+def map_pack_hash(packs: Iterable[tuple[int, int, int]]) -> str:
+    """`packs` yields `(pack_id, stars, coins)` per pack, in order."""
+
+    parts = []
+
+    for pack_id, stars, coins in packs:
+        digits = str(pack_id)
+        parts.append(f"{digits[0]}{digits[-1]}{stars}{coins}")
+
+    return sha1_hex("".join(parts) + SALT_LEVEL)
+
+
+def gauntlet_hash(gauntlets: Iterable[tuple[int, str]]) -> str:
+    """`gauntlets` yields `(gauntlet_id, comma_separated_level_ids)`, in order."""
+
+    joined = "".join(
+        f"{gauntlet_id}{level_ids}" for gauntlet_id, level_ids in gauntlets
+    )
+
+    return sha1_hex(joined + SALT_LEVEL)
+
+
+def challenges_hash(blob: str) -> str:
+    return sha1_hex(blob + SALT_CHALLENGES)
+
+
+def rewards_hash(blob: str) -> str:
+    return sha1_hex(blob + SALT_REWARDS)
+
+
+LEVEL_LIST_HASH = sha1_hex(SALT_LEVEL)
+
+
+def level_password_wire(password: str | None) -> str:
+    """The plain-text form of a copy password: `0` no copy, `1` free copy, else
+    `1` followed by the digits."""
+
+    if password is None:
+        return "0"
+
+    return f"1{password}"
+
+
+def level_password_from_wire(wire: str) -> str | None:
+    if wire in ("", "0"):
+        return None
+
+    return wire[1:]
+
+
+def level_password_number(password: str | None) -> int:
+    """The numeric form used by the download hash: the plain wire value as an
+    integer. Verified against the official server for 4 and 6 digit passwords;
+    the documented 1,000,000 normalisation is not applied there."""
+
+    return int(level_password_wire(password))
+
+
+def encode_level_password(password: str | None) -> str:
+    if password is None:
+        return "0"
+
+    return encode_xor_text(level_password_wire(password), KEY_LEVEL_PASSWORD)
+
+
+def decode_level_password(encoded: str) -> str | None:
+    if encoded in ("", "0"):
+        return None
+
+    raw = decode_base64(encoded)
+
+    if raw is None:
+        return None
+
+    return level_password_from_wire(
+        cyclic_xor(raw, KEY_LEVEL_PASSWORD).decode("ascii", "replace")
+    )
+
+
+def decode_reward_chk(value: str, key: bytes) -> int | None:
+    """Recovers the client's challenge number from a rewards `chk` parameter."""
+
+    raw = decode_base64(value[5:])
+
+    if raw is None:
+        return None
+
+    number = cyclic_xor(raw, key).decode("ascii", "replace")
+
+    if not number.isdecimal():
+        return None
+
+    return int(number)
+
+
+def encode_reward_blob(plaintext: str, key: bytes) -> str:
+    return encode_base64(cyclic_xor(plaintext.encode(), key))
+
+
+def classic_leaderboard_seed(clicks: int, percentage: int, seconds: int) -> int:
+    return (
+        1482 * 2
+        + (clicks + 3991) * (percentage + 8354)
+        + (seconds + 4085) ** 2
+        - 50028039
+    )
+
+
+def platformer_leaderboard_hash(best_time: int, best_points: int) -> int:
+    number = (
+        ((best_time + 7890) % 34567) * 601
+        + ((abs(best_points) + 3456) % 78901) * 967
+        + 94819
+    ) % 94433
+
+    return ((number ^ (number >> 16)) * 829) % 77849