PCGen is a program designed to create and manage player characters in pen & paper games like D&D. It works on Windows, Mac & Linux, basically anywhere the Java JDK works. It will let you create a character under a system of rules, track its levels and abilities as you progress, inventory and spells. It supports numerous game systems, most notably:
- D&D 3.5, 4.0, 5.0
- Pathfinder 1e
- Starfinder
PCGen is an open source program driven by cotributors, without your help no new fixes or content can be added. If you can program Java or want to contribute to expanding the book support please consider joining our team. Many of the original members have become inactive and we need new contributors to keep the project going.
To join our group:
- Join our Discord
- Post in the volunteers channel to get access to the Slack. A senior member will add you by email.
- Make an account on the JIRA bug tracker. See CODE and DATA issues. Work is tracked here to easily generate release notes.
- Review the Basic Workflow & Development Setup below to get started.
The old wiki archives historical meetings, many design documents and useful dev information. Browse it when you have time, it can provide some insight into certain parts of the architecture.
Andrew has made a series of videos explaining the LST files. These are mainly targetted at new DATA contributors adding new books/content and fixing bugs. You can of course ask questions in the discord or slack if you are unsure. Programmers may want to review these if they work on the LST parsing or related systems.
- Get a bug from JIRA primarily from the CODE or DATA sections. Alternatively if you want to propose a new feature/change, make a JIRA entry to track it.
- Create a branch in your fork of PCGen during development. It is good to name branches after ticket numbers, like fix_code_3444 or fix_data_3322.
- Work until the feature or bug is finished. Add tests if needed, especially if new code added.
- Push all work up into your copy of PCGen. Try to ensure build passes BEFORE submitting a pull request.
- Submit pull request from your fork to master and respond to review by members.
- Go back to first step.
These steps will guide you to a basic setup for development. These steps should work for Linux, Mac or Windows. Where steps differ it will be highlighted. If you have trouble, feel free to ask in the discord or slack once you have joined.
Anything written like this should be executed in a terminal.
For Windows this means opening the start menu and typing cmd.exe or Powershell. The latter is more modern if available.
For Linux or Mac, whatever default terminal you have is fine.
Check the installed version with:
java -version
You will want Java with a minimum version of 11. You can install the latest version from AdoptOpenJDK regardless of your OS, please see instructions there.
Check the installed version with:
git --version
Any version should do. You can install git on debian machines:
sudo apt-get install git
On Windows, Git For Windows is a good choice. Download and install. Be sure to install both the GUI & command line version. The default options are fine.
If you do not know about git, reading the first 3 or 4 chapters of Pro Git will go a long way. It is designed about command line but all principles apply to the GUI version.
Log in to github and go to PCGen in your browser. Fork the project to have your own copy. Clone the fork locally, if you use ssh for instance it should be:
git clone git@github.com:USERNAME/pcgen.git
Where USERNAME is your github username. This can be done on the command line, or else open the git GUI and clone from there.
Open a terminal inside the cloned pcgen project. Run the following command:
git remote add upstream https://github.com/PCGen/pcgen
This sets up the project for upstream rebasing, to keep you level with changes. You can rebase the master with latest changes with the following. It can be done from GUI as well.
git checkout master && git fetch upstream && git rebase master
This step is optional. You are free to program in what you prefer, these are several popular IDEs for Java. If you are new we would suggest IntelliJ. Follow download/setup instructions then continue. These IDEs have git and gradle plugins either out of box or that can be installed.
Once setup, open your IDE of choice. You should be able to import the cloned fork. Import the PCGen fork as a gradle project. From this point, you can work on the project. For IntelliJ Community do: File > New > Project from Existing Sources ... All of these IDEs have git and gradle plugins that can be used instead of commands.
This is a quick rundown on gradle. You can get more information from gradle docs. Gradle is like make, it allows you to run commands to build projects. The tasks can depend on one another and will ensure all dependencies are met before running. These commands will be the same if you use a GUI to execute them.
Note: ./gradlew indicates you are executing the gradle wrapper command binary that comes with PCGen's source tree.
This will automatically download and use the latest version of gradle. If you have gralde installed, you just
substitute ./gradlew for gradle on the command line.
./gradlew tasks
./gradlew compileJava
./gradlew assemble
./gradlew run
./gradlew test
Do this primarily before pull requests. This is almost exactly the command Travis runs to verify, if it fails locally you will fail the build and your PR will not be merged.
./gradlew clean build copyToOutput test compileSlowtest datatest pfinttest allReports buildDist
./gradlew clean