A PSDK project created with Pokémon Studio has no Git repository by default. Putting it under Git lets several makers work on the same game without overwriting each other. The difficulty specific to PSDK is that RMXP data is stored in binary `.rxdata` files that Git cannot merge. This guide explains how to initialize the repository, what the `.gitignore` must contain, the `.yml` workflow that makes RMXP data mergeable, and the rules that keep contributors from stepping on each other. Before starting, make sure you have done the [development environment setup](/getting-started/setup-development-environment), which installs **Git** and **VS Code**. Most steps below are done graphically in VS Code and on the GitHub or GitLab website. For the Git vocabulary used here (**commit**, **branch**, **remote**) and the optional SSH key, see [Discover Git](/getting-started/discover-git). We also recommend installing the **GitLens** extension (see [GitLens](/getting-started/setup-development-environment#gitlens-optional)). ## Put your project under Git A Pokémon Studio project is just a folder on your disk. Putting it under Git takes three steps, all graphical: create an empty repository online, add a `.gitignore`, then publish the project from VS Code. You first need a free **GitHub** or **GitLab** account. VS Code will ask you to sign in to it the first time you publish, which is also how it gets permission to push your commits. ### Create the repository on GitHub or GitLab This is done entirely from the website. On **GitHub**: 1. Click the **+** at the top right, then **New repository**. 2. Give the repository a name, and choose **Private** if the project should not be public. 3. Leave **Add a README**, **Add .gitignore** and the license options **unchecked**, so the repository stays empty and can receive your existing project. 4. Click **Create repository**. On **GitLab**: 1. Click **New project**, then **Create blank project**. 2. Give the project a name and choose its visibility. 3. **Uncheck** "Initialize repository with a README", so the project stays empty. 4. Click **Create project**. Keep the page open: it shows the repository **URL** you will need later. If you signed in to VS Code, copy the **HTTPS** URL; if you set up an SSH key (see [Discover Git](/getting-started/discover-git#setting-up-ssh)), copy the **SSH** URL (it starts with `git@`). ### Add a .gitignore Git must not track everything in the folder. A PSDK project mixes three kinds of files: **source files** you write (scripts, `.yml` data), **regenerated files** the engine recreates on its own (the Ruby runtime, the compiled `.rxdata`), and **local files** that belong only to your machine (saves). Only the source files belong in Git, otherwise the repository becomes huge and impossible to merge. Create the file at the project root (in VS Code, right-click the file list, **New File**, name it `.gitignore`) and paste the following as a base. It is the one used by the official PSDK technical demo: ```bash # Engine runtime - regenerated by PSDK/Studio, never committed .gameopts Game.rb latest.json psdk.bat lib/ ruby_builtin_dlls/ pokemonsdk/ ruby.exe rubyw.exe msvcrt-ruby300.dll # Local saves and compiled battle scripts Saves/* Data/Events/Battle/*.yarbc # Compiled RMXP data (binary) - ignored, but the .yml versions are kept Data/Actors.rxdata Data/AnimatedTiles.rxdata Data/Animations.rxdata Data/CommonEvents.rxdata Data/System.rxdata Data/Tilesets.rxdata Data/Map*.rxdata !Data/Map*.rxdata.yml Data/configs/*.rxdata !Data/configs/*.rxdata.yml Data/PSDK/Maplinks.rxdata !Data/PSDK/Maplinks.rxdata.yml Data/PSDK/SystemTags.rxdata !Data/PSDK/SystemTags.rxdata.yml # Compiled text and Studio data Data/Text/Dialogs/*.dat Data/Studio/psdk.dat # Build artifacts PSDK_Technical_Demo_*.zip Release/ project.psa ``` Two things are worth understanding here: - The engine runtime (`lib/`, `ruby.exe`, `pokemonsdk/`, `psdk.bat`, ...) is provided by Pokémon Studio or by cloning the engine. It is heavy and machine-specific, so it is never committed. Each teammate gets it on their own machine. - The compiled RMXP data (`.rxdata`) is **binary**. It is ignored, while the `!Data/...rxdata.yml` lines explicitly keep the **text** `.yml` versions tracked. This split is the whole point of the [yml workflow](#versioning-rmxp-data-the-yml-workflow) below. The `PSDK_Technical_Demo_*.zip` line is the demo's release archive. In your own project, replace it with the name of your own release archive. ### Publish your project with VS Code With the `.gitignore` in place, VS Code can publish the project without the terminal. Every action below is run from the **Command Palette**: press `Ctrl+Shift+P` and type the command. The exact button positions move between VS Code versions and are reshuffled by GitLens, so the Command Palette is the reliable way to find an action (tip: type `Git:` to list every Git action available in your version). 1. Open the project folder in VS Code: **File > Open Folder**. 2. Run **`Git: Initialize Repository`** to start tracking the folder. 3. Open the **Source Control** view (the branch icon in the left bar, or `Ctrl+Shift+G`). Because the `.gitignore` is already there, only the right files show up. Stage them all with the **+**, type a message such as `Initial commit`, then run **`Git: Commit`** (or press `Ctrl+Enter` in the message box). 4. Run **`Git: Add Remote`**, paste the repository URL from the website, and name it `origin`. 5. Run **`Git: Push`** to upload the project. On the very first push, the command may instead be named **`Git: Publish Branch`**, and VS Code may ask you to sign in to GitHub or GitLab. :::note[The first push is long] A PSDK project contains tens of thousands of files (graphics, audio, maps, data) and can weigh several hundred megabytes, so the first upload may take several minutes, or more on a slow connection. Let it finish without interrupting it: VS Code shows the progress in the bottom status bar. Once it is done, check that the **Source Control** view no longer lists pending changes, and refresh the repository page on GitHub or GitLab, where the files and the last commit should now appear. ::: If you prefer the command line, the repository page also shows the equivalent commands (`git init`, `git add .`, `git commit`, `git remote add origin `, `git push -u origin main`). ## Versioning RMXP data: the yml workflow Maps, animations, common events and configurations are saved by RMXP and Studio as `.rxdata` files. These are **binary**: when two makers edit the same map, Git cannot merge the two versions. It can only keep one and discard the other, so someone always loses their work. PSDK solves this with a round-trip between `.rxdata` (binary, used by the game) and `.yml` (text, used by Git). You commit the `.yml`, you ignore the `.rxdata`, and you switch between the two by **double-clicking** one of the two scripts at the project root: - `convert_rxdata_to_yml.bat` converts `.rxdata` to `.yml`. Double-click it **before every commit**, so the text version that lands in Git matches what you just did. - `convert_yml_to_rxdata.bat` converts `.yml` back to `.rxdata`. Double-click it **after every pull**, so the game uses the data your teammates just shared. :::warning[Close RMXP and Studio first] Always **save and close RMXP and Pokémon Studio before double-clicking either script**, in both directions. If they stay open, the data they hold in memory can overwrite the freshly converted files when you save, silently undoing the conversion (and your teammate's work). The script opens a small console window that closes on its own after a second or two; to confirm it worked, check that the `.yml` (or `.rxdata`) files just changed, or run the script from Command Prompt to read its output if something looks wrong. ::: The first time you clone the project, the `.rxdata` files do not exist yet (they are ignored), so the game would crash. Double-clicking `convert_yml_to_rxdata.bat` once after cloning is **mandatory**: it rebuilds the `.rxdata` from the committed `.yml`. The rule to memorize is short: - **Convert before you share** (`convert_rxdata_to_yml.bat`, then commit). - **Restore after you receive** (pull, then `convert_yml_to_rxdata.bat`). ## Join an existing project When you join a project that is already hosted on GitHub or GitLab, you clone it instead of creating it. In VS Code, open the **Command Palette** (`Ctrl+Shift+P`), run **`Git: Clone`**, paste the repository URL, and choose where to save it. The `.rxdata` files are not in the repository (they are ignored), so the game cannot run yet. Do this once, in order: 1. Open the project in **Pokémon Studio** once, so it generates the proper `psdk.bat`, then close Studio. 2. **Double-click `convert_yml_to_rxdata.bat`** to rebuild the binary data from the committed `.yml`. This restore step is **mandatory** on the first clone, otherwise the game crashes for lack of `.rxdata`. After that, you are set up exactly like the rest of the team. ## Everyday workflow Once everyone is set up, the daily loop on a shared project is always the same, and it is mostly clicks. Say you want to add a new map. **1. Get the latest version.** Check the branch name shown in the status bar (bottom of the window) is `main`, then run **`Git: Pull`** from the Command Palette (`Ctrl+Shift+P`). Once it finishes, with RMXP and Studio closed, **double-click `convert_yml_to_rxdata.bat`** to apply your teammates' latest changes to the game. **2. Create a branch.** Run **`Git: Create Branch`** and name it after the area you touch (see [Avoid stepping on each other](#avoid-stepping-on-each-other)), for example `maps/new-town`. **3. Do the work** in RMXP and Studio. When you are ready to share it, save and **close RMXP and Studio**, then **double-click `convert_rxdata_to_yml.bat`** to turn the data into text. **4. Commit and push.** In the Source Control view, stage your changes with the **+**, type a message such as `Add the new town map`, run **`Git: Commit`**, then **`Git: Push`** to send the branch online (the blue **Sync Changes** button in the status bar both pulls and pushes). **5. Open the request.** Right after the push, GitHub shows a **Compare & pull request** banner and GitLab a **Create merge request** banner. Click it to open a **Pull Request** (GitHub) or **Merge Request** (GitLab). A teammate reviews it, then it is merged into `main`. **6. Everyone else** runs **`Git: Pull`** in VS Code, then (with RMXP and Studio closed) double-clicks `convert_yml_to_rxdata.bat` to get your map. This loop keeps `main` always working and lets several people advance in parallel, each on their own branch. ## Avoid stepping on each other Even with the `.yml` workflow, two people editing the same map at the same time still produce a painful conflict. The real fix is organization, not tooling. These rules come from the way the PSDK technical demo is maintained. **Name branches by area.** Prefix the branch with the part of the project it touches: `maps/`, `events/`, `texts/`, `resources/`. For example `maps/new-town`, `events/new-town`, `texts/translation-new-town`, `resources/new-ui`. Anyone can tell at a glance what a branch changes. **One person per map, per category.** For a given map, the **mapping** (the tiles) and the **eventing** (the events) are two separate jobs. Only one person should hold each job for a given map at a time: - Allowed: maker A reworks the mapping of Map X while maker B works on the events of Map X. - Allowed: maker A does the mapping of Map X and also its events, because the mapping changes force some events to be adapted. - Not allowed: maker A and maker B both edit the mapping of Map X (one adds animated tiles, the other fixes something). - Not allowed: maker A fixes events on Map X while maker B adds new events to Map X. **Communicate before you start.** Always ask whether someone is already working on the map you want to touch. The branch naming convention helps, but a quick message avoids the rest. **Do Tiled conversions on your own branch.** A Tiled map conversion changes many files at once. Run it on your branch and include the result in that branch's commit, so it never collides with someone else's conversion. ## Resolve a conflict on a yml file Because maps and data are versioned as `.yml` text, a conflict is now something you can actually fix instead of losing a file. When a pull reports a conflict, the conflicted files appear under **Merge Changes** in the VS Code Source Control view. We recommend resolving conflicts in **VS Code with the GitLens extension**. Open a conflicted `.yml` file and click **Resolve in Merge Editor**. The merge editor shows both versions side by side, with **Accept Current Change**, **Accept Incoming Change** and **Accept Both Changes** buttons for each conflicting block. GitLens adds the authorship and history of each side, which helps decide which one to keep. Once a file looks right, click **Complete Merge** in the merge editor: the file moves to the staged changes. When all conflicts are done, run **`Git: Commit`** to finish, then (with RMXP and Studio closed) **double-click `convert_yml_to_rxdata.bat`** to rebuild the binary data so the game reflects the merged result. ## Conclusion - A Pokémon Studio project has no Git repository by default. With a GitHub or GitLab account, create the empty repository, add a `.gitignore` **before the first commit**, then publish the project from VS Code. - The `.gitignore` keeps source files (`.yml`, scripts) and ignores everything regenerated (engine runtime, binary `.rxdata`) or local (saves). - RMXP data is binary and unmergeable. PSDK converts it to text `.yml`, always with RMXP and Studio closed: double-click `convert_rxdata_to_yml.bat` before sharing, `convert_yml_to_rxdata.bat` after receiving, and once after the first clone (open the project in Studio first to generate `psdk.bat`). - The daily loop is: pull and restore, branch, work, convert, commit, push, then open a Pull Request or Merge Request. - To avoid conflicts, name branches by area, keep one person per map per category, communicate before starting, and run Tiled conversions on your own branch. - Conflicts on `.yml` files are resolved in the VS Code merge editor, then `convert_yml_to_rxdata.bat` rebuilds the binary data.