Skip to main content
View

Set up the development environment

Before writing scripts for a PSDK project, you need to install Ruby, configure a code editor, and set up autocompletion to have access to PSDK documentation and methods while coding. This guide covers the complete installation step by step.

Principle​

The PSDK development environment relies on three pillars:

  • Ruby: the language PSDK is written in. It must be installed on your machine.
  • Visual Studio Code (VSCode): the recommended code editor. With the right extensions, it provides autocompletion, hover documentation, and linting.
  • Solargraph: a Ruby language server that analyzes PSDK code and provides autocompletion. It needs access to the PSDK source code to work.

Installing Ruby​

  1. Go to rubyinstaller.org.
  2. Download Ruby 4.0.1 with the devkit (Ruby+Devkit 4.0.1 (x64) version).
  3. Run the installer and follow the steps. When MSYS2 is offered, accept the installation.
  4. Verify the installation by opening a terminal and typing the command below. To open a terminal, open the Start menu, type cmd, and press Enter: this is Command Prompt, the terminal used throughout this guide (not PowerShell).
ruby --version

The displayed version should start with 4.0.

Installing Git​

Git is the version control tool used throughout PSDK, and VSCode relies on it for all its source-control features. Without it, the Git steps in the next guides will not work.

  1. Download Git for Windows.
  2. Run the installer. The default options are fine: keep clicking Next, then Install.
  3. Verify it in cmd, from any folder:
git --version

A version number confirms Git is installed.

  1. Configure your identity so Git can stamp every commit with an author. Still in cmd, from any folder:
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

Use the same email as your GitHub or GitLab account so your commits are linked to your profile. The --global flag applies this to every repository on your machine, so you only do it once.

Installing Visual Studio Code​

  1. Download Visual Studio Code.
  2. Install and launch VSCode.
  3. Install the following extensions from the Extensions panel (Ctrl+Shift+X):
    • Ruby Solargraph: autocompletion, hover documentation, diagnostics.
    • Ruby LSP: advanced Ruby language support (highlighting, navigation, formatting).

Installing the gems​

Open cmd as administrator (right-click the Command Prompt entry, "Run as administrator") and install Solargraph and Ruby LSP:

gem install solargraph
gem install ruby-lsp

Configuring VSCode​

Open the User Settings (JSON): Ctrl+Shift+P, then run "Preferences: Open User Settings (JSON)". Add the following lines inside the existing { }, separating each entry with a comma:

"editor.tabSize": 2,
"solargraph.diagnostics": true,
"solargraph.formatting": false,
"rubyLsp.enabledFeatures": {
    "codeActions": true,
    "diagnostics": true,
    "documentHighlights": true,
    "documentLink": true,
    "documentSymbols": true,
    "foldingRanges": true,
    "formatting": true,
    "hover": true,
    "inlayHint": true,
    "onTypeFormatting": true,
    "selectionRanges": true,
    "semanticHighlighting": true,
    "completion": true,
    "codeLens": true,
    "definition": true,
    "workspaceSymbol": true,
    "signatureHelp": true,
    "typeHierarchy": true
},
"rubyLsp.formatter": "none",
"rubyLsp.rubyExecutablePath": "C:\\Ruby40-x64\\bin"
  • Adapt the path C:\\Ruby40-x64\\bin to the bin folder of your Ruby installation. The RubyInstaller folder name reflects the installed version (for example C:\\Ruby40-x64 for Ruby 4.0, C:\\Ruby34-x64 for Ruby 3.4).
  • editor.tabSize: 2: PSDK uses 2-space indentation.
  • solargraph.diagnostics: true: enables RuboCop diagnostics through Solargraph.

Making PSDK code visible to Solargraph​

Solargraph needs access to the PSDK source code to provide autocompletion on engine classes (Battle::Logic, GamePlay::Base, UI::SpriteStack, etc.). Since PSDK code is not directly in the scripts/ folder, you need to tell Solargraph where to find it.

There are two ways to access the PSDK code, and the choice determines how updates work:

  • Via the pokemonsdk repository: the forked repository becomes the source of truth. PSDK updates are not automatic — you must synchronize the repository with the official one yourself (see Contribute to PSDK, section "Keeping your fork up to date").
  • Via the symbolic link: the files point to the Pokémon Studio installation. When you update PSDK from Pokémon Studio, these files are updated automatically.

Generating the solargraph.yml file​

Both cases below edit scripts/solargraph.yml. If that file does not exist yet, generate it first. In cmd, from the project root:

cd scripts
solargraph config

Then follow the case that matches your project to fill in the include section.

If the pokemonsdk repository is in the project​

If the pokemonsdk/ folder exists at the project root (after forking and cloning the repository, see Contribute to PSDK), the solargraph.yml file in scripts/ should contain:

---
include:
  - "../pokemonsdk/**/*.rb"
  - ./**/*.rb
exclude:
  - spec/**/*
  - test/**/*
  - vendor/**/*
  - ".bundle/**/*"
require: []
domains: []
reporters:
  - rubocop
  - require_not_found
formatter:
  rubocop:
    cops: safe
    except: []
    only: []
    extra_args: []
require_paths: []
plugins: []
max_files: 5000
  • "../pokemonsdk/**/*.rb": tells Solargraph to include all Ruby files from the pokemonsdk repository. This is the relative path from scripts/.
  • ./**/*.rb: also includes all user scripts in scripts/.

If the repository is not in the project (standard Pokémon Studio project)​

For a project created with Pokémon Studio without forking the repository, the PSDK scripts are bundled internally by Pokémon Studio. You need to create a symbolic link so Solargraph can access them.

Open cmd as administrator, navigate to the scripts/ folder of the project, and create the link:

cd C:\path\to\your-project\scripts
mklink /D psdk_scripts "%temp%\..\Programs\pokemon-studio\resources\psdk-binaries\pokemonsdk\scripts"
  • mklink /D creates a directory symbolic link. Administrator mode is required. This command is specific to cmd (do not use PowerShell).
  • psdk_scripts is the name of the virtual folder that will appear in scripts/. Do not put your own scripts in it.
  • The target path points to the PSDK Ruby sources in the Pokémon Studio installation. %temp% is used to reach the user's Programs folder.

Check that the link worked: open the new scripts/psdk_scripts folder in the file explorer, it should show PSDK's .rb files. If it is empty, Pokémon Studio is installed elsewhere on your machine; adjust the target path to point to its resources/psdk-binaries/pokemonsdk/scripts folder.

Then adapt the solargraph.yml to include this link:

---
include:
  - "psdk_scripts/**/*.rb"
  - ./**/*.rb

The rest of the file remains identical.

Configuring RuboCop​

RuboCop checks that code follows PSDK conventions (explicit returns, no for loops, etc.). The configuration is in the .rubocop.yml file. If this file does not exist in scripts/, copy it. Run the command in cmd, from the project root.

If you forked the pokemonsdk repository, copy it from there:

copy pokemonsdk\scripts\.rubocop.yml scripts\.rubocop.yml

For a standard Pokémon Studio project, copy it from the symbolic link created earlier (so do this only after the link exists):

copy scripts\psdk_scripts\.rubocop.yml scripts\.rubocop.yml

RuboCop activates automatically through Solargraph. Code lines that do not follow conventions will be underlined in blue in VSCode.

Opening the right folder in VSCode​

Always open the scripts/ folder in VSCode, not the project root. In cmd, from the project root:

code scripts

This is the folder where Solargraph and RuboCop look for their configuration files (solargraph.yml, .rubocop.yml). If you open a different folder, autocompletion and linting will not work.

Checking that the code is being parsed​

When the folder opens, both language servers start and parse the Ruby files. On the first launch this can take a while (longer on slower machines), and autocompletion or hover documentation stay empty until it finishes. An empty result usually means parsing is still running, not a broken setup. There are two ways to follow its progress:

  • Ruby LSP shows its progress in the status bar at the bottom of the window ("Initializing Ruby LSP", then an indexing indicator).
  • Solargraph (the server that reads solargraph.yml and provides PSDK engine completion) does not use the status bar. Open the Output panel (Ctrl+Shift+U, or View menu, then Output) and select Ruby Language Server in the dropdown: its log shows the parsing in progress and any configuration error, such as a wrong path in solargraph.yml.

If autocompletion still shows nothing once parsing has finished, restart Solargraph: Ctrl+Shift+P, then run "Restart Solargraph".

How PSDK loads your scripts​

Configuring Solargraph only affects the editor. It does not change which files PSDK actually runs. The engine loads a script from scripts/ only if its filename starts with 3 to 5 digits, then a space, then the name, for example:

001 Test.rb

A file named test.rb or pokemon_name.rb is ignored by the engine: Solargraph still autocompletes it, but it never runs in-game, which is a common source of confusion. Official PSDK scripts use 3 digits; 4 or 5 also work, so older projects numbered on 5 digits keep loading. An underscore is accepted in place of the space (001_Test.rb), but the convention is a space.

PSDK loads these files in ascending order of their number, then alphabetically when numbers are equal. The number therefore controls the load order:

  • Two independent files can share the same number without any conflict: 007 James.rb and 007 Bond.rb both load (Bond before James, alphabetically).
  • If a file depends on a class or constant defined in another, the file it depends on must have the lower number. Loading 020 Battler.rb before the 010 Creature.rb it relies on crashes at startup.

Subfolders inside scripts/ follow the same logic: PSDK only descends into a subfolder whose name also starts with a number (for example 001 My Plugin/), and the files of a folder load before those of its numbered subfolders.

Testing the environment​

To verify everything works, create a test script named 001 Test.rb in scripts/ (the number prefix is required for PSDK to load it in-game, see the previous section):

# Get the name of a Pokemon from its db_symbol
# @param db_symbol [Symbol] the db_symbol of the Pokemon
# @return [String] the name of the Pokemon
def pokemon_name(db_symbol)
  return data_creature(db_symbol).name
end
  • When typing data_, Solargraph should suggest data_creature in autocompletion. If it does, the environment is correctly configured.
  • When hovering over pokemon_name with the mouse, VSCode should display the YARD documentation (description, parameter, return).
  • If lines are underlined in blue, RuboCop is working. Fix the warnings to verify that the PSDK configuration is active (for example, explicit return should not be flagged as redundant).

To test in-game, launch the project. In cmd, from the project root:

psdk debug skip_title

Load a save, then call the method in the debug console:

pokemon_name(:pikachu)

If the console displays "Pikachu", everything is in place.

GitLens (optional)​

When working with others (see Work together on a PSDK project), the GitLens extension is a useful addition to VSCode. It shows, directly in the editor, who last changed each line, the history of a file, and the contributors of the project, which helps coordinate work and resolve conflicts.

Install it from the Extensions panel (Ctrl+Shift+X) by searching for GitLens.

You can also choose which GitLens views appear in the Source Control view, by adding the following setting to the same User Settings (JSON) as above, inside the existing { }. For each view, false keeps it visible and true hides it, so the configuration below hides the Contributors and Tags views and keeps the others:

"gitlens.views.scm.grouped.views": {
    "branches": false,
    "commits": false,
    "contributors": true,
    "launchpad": false,
    "remotes": false,
    "repositories": false,
    "searchAndCompare": false,
    "stashes": false,
    "tags": true,
    "worktrees": false
}

Conclusion​

  • Install Ruby 4.0.1 with the devkit, then the gems solargraph and ruby-lsp.
  • Install VSCode with the Ruby Solargraph and Ruby LSP extensions. Configure the User Settings (JSON) for tabsize, diagnostics, and the Ruby path.
  • Make PSDK code visible to Solargraph via solargraph.yml: either a relative path to pokemonsdk/, or a psdk_scripts/ symbolic link.
  • Copy PSDK's .rubocop.yml into scripts/ so RuboCop uses the project conventions.
  • Always open the scripts/ folder in VSCode so Solargraph and RuboCop find their configurations.
  • Name every script NNN Name.rb (3 to 5 digits then a space) so PSDK loads it; the number sets the load order.
  • Optionally, install GitLens for Git history, blame and contributor information, useful when collaborating on a project.