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
clonein your PSDK Fork details. Take the SSH URL otherwise it'll be hard to push.
- You can get the URL by clicking on
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 developmentgit pullgit 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
- You should not commit your changes to the
developmentbranch. You have to make a merge request from your feature/bugfix branch to the official (pokemonsdk/pokemonsdk) development branch. - 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)
- You should always make sure that your branch is up-to-date with the development branch using the git rebase feature
- 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
- Select the project
- Click on the
Compare branches and continuebutton
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:
Fixif this is a bug fixAddorImplementif this is a new featureUpdateorChangeif this is a feature updateRewriteorRefactorizeorImproveorReworkif this is a code refactorization or a feature improvementRemoveorRevertif 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
pokemonsdkfolder (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 testedlabel in any case
- Add the
- Check
Delete source branch when merge request is accepted. - Check
Squash commits when merge request is accepted. - Click on
Submit merge requestbutton
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
ruby3.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\\binby 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 executingtasksat 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 the00100 PSDK_Taskscript to see how it's used.Studio: This module contains all the classes &dead datahelpers. Thedead datais the data that is stored inside the.rxdata,.csvor.datfiles, 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 thatNuriYurimade. You should never add any script inside it. (But you can fix some features)PFM: This module contains all the classes &living datahelpers. Theliving datais the data that is manipulated duringruntimeand that can be expected to be saved in the player save file.UI: This module contains all the classes that are expected to performGraphicdisplay/help. Those classes should not have logic inside (or just tiny logic if that helps the display like index adjustment). Most of the classes insideUIshould inherit fromUI::SpriteStack,SpriteorUI::Window.GamePlay: This module contains all the scenes that are called and stored inside the$sceneglobal. If you make a new scene, you have to make it inherit fromGamePlay::Base(or a specializedGamePlay::Baseclass) and you should never edit themainfunctions or read/write the$scenevariable. A tutorial will be made later aboutGamePlay::Base.BattleUI: This module contains all the UI of the Battle Engine. That's somehow the same asUIbutUIis currently not included inside so you need to explicitly writeUI::ClassNameif you use a class fromUIinBattleUI.Battle: This module contains all the Battle Engine related classes (Scene,Logic,Visual,AIandMove).
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) endinstead 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 endAlternatively, use
rejectto perform the opposite. -
ary.collect { |element| transformation }orary.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_inputsfor 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_graphicsto 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_ui
end
def update_inputs
# ...
end
private
def
@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_Menuis 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.