Improving the engine
For non-programmers[edit]
Even if you don't know how to program, and don't want to learn, you can still help us. Just download the latest nightly build and test it for bugs. If you find a bug, report it.
Improvements to the documentation (F1 help files), the plotscripting dictionary (see Improving the Plotscripting Dictionary), and the wiki are also very welcome. You can also submit new script commands which are implemented as scripts in plotscr.hsd (please include plotscripting dictionary entries).
For programmers (and people who want to learn)[edit]
If you want to become an OHRRPGCE developer, you must know how to program. We use mostly FreeBasic as the language (with portions of Python, C++, C, and Euphoria and of course HamsterSpeak), so knowing that helps, although the syntax is easy enough to pick up if you're familiar with any other language. For certain specific tasks like improving HSpeak (written in Euphoria), or gfx_directx (written in C++), FB knowledge is not needed. Use of FB is also not required for new self contained code (say, a new backend for MIDI playback) and we are increasingly using C and C++. Also, most of our scripts and tools are written in Python.
The next thing you need to do is become familiar with the project. Know what the engine can and cannot do. Use Subversion or Git, and check out a copy of the source code. Try to get it to compile. Once you have successfully compiled Game and Custom yourself, you are ready to start making changes to the source code.
Finding the part of the source code that you want to change and how it works is probably going to be the biggest challenge for a beginner. The code is not always well organized, so discovering which routine in which file is responsible for the part of the program you care about can require a lot of detective work. Try Guide to source files as a starting point. Don't hesitate to ask on the mailing list, create a thread on Slime Salad or try to find James or TMC in Discord (there's a channel for discussing engine development). They'll be pleased to answer questions.
Bugfixes[edit]
If you write a patch to fix a bug, we will be delighted.
Check out the Buglist for a list of outstanding bugs. Be sure to read the comments that people have left on the bugs, so that you know what we've tried or not tried thus far.
Once you fix the bug, you then need to test it. This cannot be stressed enough. You need to make sure that:
- The bug is, in fact, fixed
- You did not introduce any other bugs. You should at least run the test cases to check they still pass.
Once you've determined the quality of the patch, attach it to the bug report. One of the developers will review it, and then either accept it and commit it to the source, or reject it, and tell you what's wrong with it.
New Features[edit]
If you've hacked a new feature in to the OHRRPGCE (and by hacked, I mean written in a non-hackish way), you can submit a patch or pull request; see Source#Submitting Improvements.
However, if it's anything significant it would be a very good idea to discuss it with us first, as we've already planned out a lot of future features or even started on them. It's likely that we'll suggest an alternative way to achieve the feature. For example we try to make new features as general as is reasonable, and to make them fit with future plans. But if there's already a plan written up for it you can probably jump straight in.
But, make sure you've tested it, and that it doesn't break other things. We've been bitten by this before: too many new features + not enough testing = bad release. Just running test cases isn't enough. Since you have to test it anyway, consider doing so by adding test cases to autotest.rpg (or interactivetest.rpg or elsewhere) if it's possible to test with a script. However most features can't easily be tested, or completely tested in this way, and we won't insist on test cases (it can be a lot of work...).
Help with adding features[edit]
- How to add a new script command
- We already have loads of features and their implementation planned out on the Plans page
- Developer Notes provides some help with FreeBASIC and quirks in the source code
- Try checking Category:OHRRPGCE Development or Category:OHRRPGCE Internals
- Of course, ask on the mailing list, IRC, or even the forums, for help and advice!
Documentation[edit]
If you change anything, you should update (or add...) the relevant Documentation as well. Please:
- Add a note to whatsnew.txt in your patch if it's a non-trivial feature or bugfix
- Update plotdict.xml if you added/changed any commands (it's not necessary to re-generate plotdictionary.html)
- Update the relevant file formation documentation on the wiki if you changed anything (Mark changes with {{WIP|inline}})
- Add details to any ohrhelp/*.txt files if you added or changed anything in Custom
- If you add something like a debug menu to Game then a help file for that would be nice too
- Have a look for articles on the wiki that need updating. There are heaps of out of date articles on the wiki which are too much work to update, so there's no need to fix up everything. There are only a few pages like What are the debugging keys? and What are the limits on various things? that should definitely be kept current. It would be ideal if the HOWTO were kept up to date... but we don't :( (Mark things which refer to nightly builds with {{WIP|inline}} or {{WIP}})
- Post a thread on the Forums to show off your feature, so that others will know about it! Really, this is a good idea if it's a significant feature.
- Add yourself to the Developers page :)
Test cases[edit]
We have some test cases for Game, though these only test a relatively small part of the engine. There are also separate testcases for RELOAD, ReloadBASIC, some util.bas functions, vectors and more, which are compiled into standalone programs. Run scons test to run all tests, or scons autotest and scons interactivetest for just the Game tests.
However this does NOT run the complete tests in autotest.rpg, as it doesn't check that everything is drawn correctly (for example, maybe an NPC is in the wrong spot). To perform these checks, use autotest.py instead. The most common use is autotest.py testgame/autotest.rpg. See autotest.py --help for more options. This is much more laborious than just running scons test, so we only do so irregularly.
And...[edit]
If you prove yourself to be a worthy developer, by fixing bugs and adding new features, you may become a full developer with direct write access to the source code, so you don't have to keep submitting patches, and bothering us waiting for us to review it.