Creating Maps
Build your own code maps to share with the community
What is a Code Map?
A Code Map is a collection of code locations from GitHub repositories. Each location specifies a file at a specific commit and a range of lines that will be hidden during gameplay. Players must figure out what code belongs in the masked section.
Getting Started
To create your own map, go to My Maps and click "Create Map". You'll need to be logged in with your GitHub account.
Adding Locations
Each location in your map is defined by GitHub URL pointing to a specific line or range of lines in a file at a specific commit. The URL format is:
https://github.com/owner/repo/blob/commit/path/to/file.py#LNN[-LMM]
The beauty of these URLs (Uniform Resource Locators) is that they unambiguously locate a resource of few lines of code, and you can also paste them into your browser to see that code in context. These are some real, clickable examples:
https://github.com/nodejs/node/blob/8e41b8d0c2d4e6312a6b8d2ebe17b7f211020532/lib/domain.js#L297-L300
The lines are specified in the URL hash, as a single line number (e.g., #L10) or as a range for multiple lines (e.g., #L10-L12). The URL must reference a specific commit hash (not a branch name or tag) to ensure the location stays stable.
Note that GitGuessr clones and backs up the repository when you add a location, so games will keep working even if a repo or a commit goes away.
Importing and Exporting as JSON
You can export your map as JSON for backup or sharing and import locations in the same format:
{
"name": "My Map",
"description": "Optional description",
"difficulty": "EASY",
"locations": [
{ "url": "https://github.com/owner/repo/blob/commit/file.py#L10-L12" },
{ "url": "https://github.com/owner/repo/blob/commit/file.py#L42" }
]
}Difficulty must be one of: EASY, MEDIUM, HARD.
The JSON file format is useful for programmatically generating maps. It's also the input and output format of the Mapper Chrome extension (see below).
Managing Locations with Mapper (Chrome Extension)
It can be easiest to manage locations for a map while browsing a repo in the GitHub web UI. The Mapper Chrome extension does just that, enhancing the GitHub UI with tools to add and remove code locations to a map.
Install the extension from the Chrome Web Store. Open Mapper via the extension icon in the Chrome toolbar and create a map or add a map by uploading a JSON file. When you browse a GitHub repo at a specific commit now, you can add locations to the map by selecting a range of lines in the GitHub code viewer. Locations already added to the map are highlighted with a blue badge and can be removed by clicking on it.
Language Support
GitGuessr recognises the following programming languages: JavaScript, TypeScript, Python, Java, C, C++, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, Scala, Shell, HTML, CSS, SCSS, Sass, Less, Vue, Svelte, Dart, SQL, Groovy, Perl, Lua, Objective-C, Elixir, Markdown, JSON, YAML.
However, it currently only has deeper support for AST comparison during gameplay (which ignores comments and irrelevant whitespace when checking a player's guess) for the following languages: JavaScript, TypeScript, Python.
GitGuessr detects the language of a location by its file extension only, so there may be some edge cases where it misclassifies code (e.g., files without an extension, C vs C++).
If you are looking for support for another language, email us!
Tips for Good Locations
1. Choose code that can be inferred from context. The surrounding code, imports, variable names, and comments should give clues about what's hidden.
2. It helps if the selection of lines can be parsed in its programming language in isolation. If GitGuessr can parse the lines into an AST, it will compare it to the AST of a player's guess, ignoring comments and irrelevant whitespace. This makes the comparison more robust and fairer to the player.
3. Avoid hiding arbitrary code like magic numbers or unique identifiers that can't be guessed. (Avoid anonymous functions with arguments as the argument names cannot usually be guessed.)
4. Test your locations! Play through your map to make sure the hidden code is discoverable.
Ideas for Maps
Need some inspiration? Just a few ideas on potentially fun and/or educational maps:
- Take a data structures and algorithms repo for a specific language and turn it into a fun way to study those algorithms.
- Pick a large, popular open source project and create a map to help new contributors explore the project.
- For a type of library (e.g., socket programming, web servers, md5 hashing) pick locations across projects in multiple languages for players to challenge themselves on how well they understand the patterns for that kind of library.