How to contribute to PSDK scripts

[!NOTE] To read this file the intended way, open this file using Visual Studio Code (VSCode) and type CTRL+K, then V. It will open the preview of this file. You can also read it on the official GitLab repository of PSDK. Enjoy your reading!

Fork PSDK

  • Go to the PSDK Repo
  • Click on the fork button

Set your local repository

In your Pokémon SDK folder, open cmd.bat and enter the following commands :

  • cd pokemonsdk
  • git remote set-url origin your_ssh_url
    • You can get the URL by clicking on clone in your PSDK Fork details. Take the SSH URL otherwise it'll be hard to push.
  • git pull

When making a new feature or a bugfix

You should follow the branch naming convention :

  • Feature branches are named like this : feature/us-ID name
  • Bug fix branches are named like this : bugfix/us-ID name

To make your new feature/bugfix, enter the following commands in your pokemonsdk folder :

  • git checkout development
  • git pull
  • git checkout -b name_of_the_branch

You'll now be able to work on what you need to.

Note : You should never commit inside development. Your local development branch must stay identical to the one from the official repository (pokemonsdk/pokemonsdk). If you commit on it by mistake, your future branches will diverge and won't be able to rebase properly. To fix this, checkout development and run :

git reset --hard origin/development

When committing to your branch

If your branch aims to fix a bug, make sure the last commit contains the following in the commit message : Fix #id_of_the_issue

When you merge with the official development branch it'll close the issue.

Before merging to development

  1. You should not commit your changes to the development branch. You have to make a merge request from your feature/bugfix branch to the official (pokemonsdk/pokemonsdk) development branch.
  2. You have to test your feature or your bugfix.
    • The PSDK project should be able to boot
    • All the PSDK features should work like they worked before (except the one you fixed obviously)
    • Your feature/bugfix should not introduce a new bug (we won't get mad if you didn't see any new bugs)
  3. You should always make sure that your branch is up-to-date with the development branch using the git rebase feature
  4. You should solve all the conflicts

:warning: Please note that any Merge Request that causes regressions or does not meet these conditions may be rejected and/or closed.

When making the Merge Request (MR)

  • In Source branch
    • Select your project
    • Select the branch you want to merge with PSDK development
  • In Target branch
    • Select the project pokemonsdk/pokemonsdk
    • Select the branch development
  • Click on the Compare branches and continue button

You'll see the New Merge Request UI

  • In Title put a title that is a bit more explicit than the branch name and always start your title using a verb:
    • Fix if this is a bug fix
    • Add or Implement if this is a new feature
    • Update or Change if this is a feature update
    • Rewrite or Refactorize or Improve or Rework if this is a code refactorization or a feature improvement
    • Remove or Revert if this is a code deletion
  • In description, with the provided template
    • describe the goal of the merge
    • add reference to issues if needed
    • tell us if you added files that aren't supposed to be in the pokemonsdk folder (graphics for example)
      • You can put a link to a 7z archive that adds all the new resources by simply extracting it in the project root
  • Assign the review to a code maintainer if possible
  • Add labels that can make the merge request more obvious about the field of application
    • Add the Need to be tested label in any case
  • Check Delete source branch when merge request is accepted.
  • Check Squash commits when merge request is accepted.
  • Click on Submit merge request button

After submitting Merge Request

If your merge request is still unnoticed or didn't get merged after one week, you should contact the PSDK contributors or the testers through the Pokémon Workshop Discord (you'll find a link on the website). Although an automatic webhook reports all the actions on the main GitLab repository to the community, it may happen that sometimes a merge request gets overshadowed by new comments or new merge requests. If this happens, just let anyone from the team know and we'll get to your merge request ASAP!

:warning: Please note that the MR requester should not mark threads opened by reviewers as resolved. Reviewers will close threads as soon as their comments have been addressed through corrections or their questions answered.

The coding rules

PSDK is a Ruby Project. It uses tools that work well with Ruby.

What editor to use ?

To edit the scripts :

  • You need to use Visual Studio Code.
  • You'll need to install ruby 3.0.6 with the devkit (MSYS2 on Windows, Ruby Installer gives you the choice to install it).

Setup the required extensions to ensure your code follows the good practices

If you don't setup these extensions, your code might not follow the good practices and future code reviews will point that out. Assuming you're using VSCode, here are the steps you need to follow.

  • Install the "Ruby LSP" VSCode extension
  • Install the "Ruby Solargraph" VSCode extension
  • Open a cmd in Admin, then run this command: gem install solargraph && gem install ruby-lsp
  • In VSCode (assuming you're using VSCode in english), tap CTRL+P, then '>', then select "Preferences: Open User Settings (JSON)"
  • In this JSON, paste this between the present brackets (or after your own configuration if you already have one), and don't forget the commas:
    "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:\\Ruby30\\bin"
  • On the last line, make sure to replace the C:\\Ruby30\\bin by the filepath of the bin folder of your Ruby version. Most generally, it'll be located in C:, and be called Ruby30 (for Ruby 3.0), Ruby31 (for Ruby 3.1), etc. Ruby LSP might not launch if not properly done.
  • Reboot VSCode, then verify on the bottom-right part of VSCode that the messages about "No bundle found" and "No .ruby-version-file found" are displayed, in this order. If that's the case, then it's a good sign you've done it right.
  • Wait a few seconds as Ruby LSP can be a bit slow to initialize depending on your hardware.
  • Rubocop should now be policing your code. You can test whether it's the case or not by writing your worst piece of code, like several guard clauses without any line break or a single return value surrounded by parenthesis. If a blue line appears under your monstrosity then you've completed this task!

What folder to open with VS Code ?

With VS Code you'll have to open the scripts folder of the pokemonsdk local repo. This folder is configured to define all the rubocop rules that PSDK uses.

What are the exact coding rules ?

Inside a script

  • Any code you write should not be underlined in blue or orange. If you think one of the rules is stupid, tell us so we can discuss a potential change to the ruling.
  • You should not lose time to fix old lines that are underlined in green or orange.
  • You should document your code using the YARD format (List of tags).
  • Splitting your methods (aka functions) into smaller methods allows makers to easily patch parts of the code instead of rewriting larger chunks of code.
  • If Solargraph fails to give you the right completion for an instance variable, use the # @type [ClassName] before creating the instance variable.

Naming of the script

All the PSDK scripts are named like this : XXX Name.rb

  • X is a number between 0 and 9, it allows sorting between scripts
  • Name should be the name of the class/module + the context when the class is separated in various scripts.

Note : Old scripts have the following name Module__Class, don't do this any more, the folder already tells us the module.

In which module to put the new features ?

Here is the official list of PSDK modules with their meaning :

  • Scheduler : This module is not used to contain classes. This is the module responsible for executing tasks at certain points of the game without adding lines inside the scripts to explicitly call your features. A tutorial about how to use it will be made later, you can check the 00100 PSDK_Task script to see how it's used.
  • Studio : This module contains all the classes & dead data helpers. The dead data is the data that is stored inside the .rxdata, .csv or .dat files, it's data that PSDK should not edit/change/save and uses as source of information (exp curve of a Pokémon for example).
  • Yuki : This is an old module coming from the time PSDK didn't exist. It contains all the features that NuriYuri made. You should never add any script inside it. (But you can fix some features)
  • PFM : This module contains all the classes & living data helpers. The living data is the data that is manipulated during runtime and that can be expected to be saved in the player save file.
  • UI : This module contains all the classes that are expected to perform Graphic display/help. Those classes should not have logic inside (or just tiny logic if that helps the display like index adjustment). Most of the classes inside UI should inherit from UI::SpriteStack, Sprite or UI::Window.
  • GamePlay : This module contains all the scenes that are called and stored inside the $scene global. If you make a new scene, you have to make it inherit from GamePlay::Base (or a specialized GamePlay::Base class) and you should never edit the main functions or read/write the $scene variable. A tutorial will be made later about GamePlay::Base.
  • BattleUI : This module contains all the UI of the Battle Engine. That's somehow the same as UI but UI is currently not included inside so you need to explicitly write UI::ClassName if you use a class from UI in BattleUI.
  • Battle : This module contains all the Battle Engine related classes (Scene, Logic, Visual, AI and Move).

If you write a feature, you should write it in the correct module according to what the feature does. When you make a scene, it's important to not write graphics related stuff inside the scene (do it inside UI with a dedicated class) and spawn the UI class instance inside an init_xxx of your Scene. (This allows the maker or specialized class to change the UI used by modifying the init_xxx method).

Specific rules

As you may see inside PSDK (putting the RMXP basic scripts aside) we do things a certain way, here are some rules you should follow to be compatible with PSDK or make good scripts :

Never use for or dynamic Ranges

The for keyword is forbidden because its meaning in Ruby is not the same as in C or in Algorithm.

for i in 0...5 do
  p i
end

Is the strict same as :

(0...5).each do |i|
  p i
end

Ruby has a powerful Iteration/Enumeration system, you should use the following methods instead of for loops :

  • int.times { |i| ... } instead of :

    for i in 0...int do
      ...
    end
    
  • min.upto(max) { |i| ... } instead of :

    for i in min..max do
      ...
    end
    
  • max.downto(min) { |i| ... } instead of :

    for i in min..max do
      j = max - (i - min)
      ...
    end
    
  • beg.step(last, step_val) { |i| ... } instead of :

    for i in beg..last do
      next if i % step_val != 0
      ...
    end
    
  • Use

    var = Array.new(size) do |i|
      ...
      next(element)
    end
    

    instead of :

    var = []
    for i in 0...size do
      ...
      var.push(element)
    end
    
  • ary.select { |element| condition } instead of :

    result = []
    for i in 0...ary.size do
      result.push(ary[i]) if condition
    end
    

    Alternatively, use reject to perform the opposite.

  • ary.collect { |element| transformation } or ary.map { |element| transformation } instead of :

    array = ary.clone
    for i in 0...ary.size do
      array[i] = transformation
    end
    
  • ary.any? { |element| condition } instead of :

    result = false
    for i in 0...ary.size do
      next unless condition
      result = true
      break
    end
    
  • ary.all? { |element| condition } instead of :

    result = true
    for i in 0...ary.size do
      next if condition
      result = false
      break
    end
    
  • ary.inject(0) { |sum, element| sum + element.property } if you need to get the sum of a property of the elements in an array. (Like the total level sum of the party).

Note about the block syntax : If the code uses only one line we use the { |*params| } syntax, if the code uses more lines we use the do |i| lines end syntax. Rubocop will tell you if you don't respect the rule.

We strongly discourage the use of dynamic Ranges when it's not needed because it creates unnecessary objects when there are other alternatives.

If you want to allow maker customization, use methods or constants

For example if the user wants to change the background of the UI for a darker one, you may use a COLORS constant that lists all the color IDs you use in the Interface. This way the maker can change the content of COLORS to use colors that are more adapted to its UI.

If you only use one or two colors you can make methods like default_color or highlight_color that return the ID of the color you use.

The same goes for filenames, window builders, etc.

Don't write all the logic inside update in Scenes

The best thing is to make your Scene inherit from GamePlay::BaseCleanUpdate and define:

  • update_inputs for the inputs logic (not called if messages are processing)
  • update_mouse(moved) for the mouse logic (not called if update_inputs returns false or messages are processing)
  • update_graphics to update the graphics animation each frame

Don't update text each frame

Text is a heavy process, you should only update it when needed and if the update can change something. By the way, the scene should not manage text objects, it should only manage UI::ClassName objects that are either UI::SpriteStack or UI::Window specializations.

Call the data= method of UI::ClassName only if the content it shows changes

The PSDK UI system relies on a data= method for dynamic text, sprites, stack or window. It allows to tell what to show without writing everything inside the Scene. You should only call this method when index changes (index_changed method from GamePlay::Base) or when the display object has to be changed (update of its internal info like the item held for a Pokémon).

Make the methods that should not be called outside of the class private

In a class, some methods like init_ui should not be called from the exterior (encapsulation). Make them private by putting them at the end of the script after the private keyword.

Example :

class Thing < GamePlay::BaseCleanUpdate
  def initialize
    super
    init_viewport
    init_ui
  end

  def update_inputs
    # ...
  end

  private

  def init_viewport
    @viewport = Viewport.create(:main, 500)
  end

  def init_ui
    @ui = UI::Thing.new(@viewport)
  end
end

Use attr_reader instead of attr_accessor and define the property= method

This rule has the goal to ensure you validate all the data. For example, setting the HP of a Pokémon should not allow Float hp value and has to update the hp_rate (to help HP bars).

Define property_text methods instead of using format sprintf etc

When a property has to be displayed in a UI, it's better to define a property_text method that generates the string the UI should show. This way you reduce the code & code duplication inside the UIs since you only need to add a SymText with :property_text as parameter.

Never use set_ or get_ names

We did this in the past but it's a bad idea. In the web documentation that separates the methods since they're sorted by name (and it also makes it harder for someone to find the method).

Favor the direct property name or property= method. If you have specialization like a property that is an Integer ID but you want to return the db_symbol, add the specialization after the name of the property : property_db_symbol for example. (Like we did for property_text).

Always use explicit return

Ruby allows returning the last evaluated expression implicitly, but in PSDK we always use explicit return. Similarly, in blocks that return a value, we always use explicit next.

# Good
def level_text
  return "Lv. #{@level}"
end

var = Array.new(size) do |i|
  next(i * 2)
end

# Bad
def level_text
  "Lv. #{@level}"
end

var = Array.new(size) do |i|
  i * 2
end

Try to limit the number of lines in one script to 500 or 1000

If the script has too many lines, it's doing too many things (no Graphics / Logic Separation, God Classes). We should not have such things. If the script is too long (because sometimes it shows various menus for example) you have different ways of doing things :

  • Use specialization : The way Party_Menu is done is wrong, it's doing too many things and it should be separated into various specialized classes.
  • Split the script in contextual scripts : The solution we took for most scripts, you can put the initialization in the first script, the update in the second script, mouse specific stuff in the third script etc...
  • Make a better separation of the actions. If your logic is too complicated (like the Battle logic) don't put it in the Scene, make a dedicated class. When we read the few lines of a script, we should understand what is done without reading the contents of the methods.