Geometry Dash server reimplementation in Crystal
Go to file
2024-02-23 12:50:32 +01:00
.vscode custom song system more-or-less outlined 2023-01-02 09:56:04 +03:00
db/migrations basic notifications impl for back-end 2023-01-16 20:26:52 +03:00
docs polish up html endpoint stuff 2023-01-03 20:47:12 +03:00
public refactor level parsing slightly 2023-05-26 16:33:07 +03:00
src replace is_admin with rank in 2024-02-08 09:43:19 +01:00
.editorconfig some minor refactoring 2022-12-30 19:04:27 +03:00
.env.example change default db location 2023-01-05 17:12:03 +03:00
.gitignore basic song downloader backend 2023-01-01 08:45:22 +03:00
config.example.toml remove a couple of todos 2023-01-10 12:13:06 +03:00
flake.lock update flake 2023-05-23 10:42:17 +03:00
flake.nix fix? flake 2023-05-23 09:10:31 +03:00
LICENSE some minor refactoring 2022-12-30 19:04:27 +03:00 config readme appendum 2023-01-06 13:03:22 +03:00
shard.lock fix toml version 2024-02-03 17:06:02 +01:00
shard.yml fix toml version 2024-02-03 17:06:02 +01:00
shards.nix update flake 2023-01-11 18:04:25 +03:00


a Geometry Dash server reimplementation in Crystal, focusing on speed and 1:1 recreations of vanilla GD features

this project is still in its very early stages. you can see a rough estimate of the current progress in this issue.


i was highly disappointed with the lack of options in private server choices - the two most well known ones that i noticed were Cvolton's GDPS which has very little customization and some of the most atrocious code i've seen in a while (though i can't really blame it, being written in PHP), and Realistik's buzzword-filled Python GDPS which i find hard to believe is seriously trying to sell itself with docker and mongodb.

i was also disappointed with the sheer simplicity of servers - most will get data and serve data and that's about it, but looking into how they're implemented made me realize many security pitfalls in Geometry Dash's server structure. for instance - even if you're storing the amount of objects a level has, you're trusting the client that they've given you an accurate count, and they could really have way more, making games unexpectedly severely lag or crash.

additionally, the lack of configuration compelled me even more to write my own solution, so one night of considering XKCD 927 later, here we are


  • crystal gauntlet is cross-compatible with many SQL engines - while SQLite will recieve the most amount of support due to the sheer ease it gives when debugging, PostgreSQL, MySQL, etc. are also supported
  • being written in Crystal, it's compiled, lightweight and extremely fast - a typical getGJLevels request will take about ~700µs, authorization is highly cached and will typically have no impact on requests and extensive amounts of effort are done to ensure the sql database structure is as efficient as it can get
  • crystal gauntlet is highly configurable letting you enforce object limits, ban certain objects, disable certain song reuploading sources and much more
  • it takes the time to parse uploaded levels to make sure nothing malicious gets through, and it gets away with it performance-wise, too
  • it utilizes yt-dlp and ffmpeg to let you reupload songs from YouTube, SoundCloud, and 1700+ other sources, all of which can be toggled on or off


shards install && shards build


copy .env.example to .env and fill it out, same for config.example.toml -> config.toml

by default, the config emulates vanilla GD servers as closely as possible, but you'll likely want to change it - most options have comments detailing what exactly they do


run bin/crystal-gauntlet migrate (or shards run -- migrate)

schemas are highly unstable so you will be offered 0 support in migrating databases for now, however in the future you'll want to run this each time you update

then bin/crystal-gauntlet (or shards run) to start the server

attributions & credits