Development Environment Setup

This article introduces the basic workflow for setting up a local development environment for PCL Community Edition, submitting changes, and opening a Pull Request. After completing the setup described in this article, you should be able to clone the repository locally, build the project, develop changes, and submit them to GitHub.

If you are already familiar with Git, .NET desktop development, and the GitHub Pull Request workflow, you may focus on the “Basic Environment Requirements”, “Initialize the Solution”, and “Open a Pull Request” sections.

System Requirements

PCL CE targets .NET 8 Desktop. Running and debugging it requires Windows 10 Version 1607 or later. This article assumes that you are developing on a relatively recent Windows system.

If you use Linux, macOS, or an older version of Windows, please configure a Windows virtual machine for debugging, or upgrade to a supported system version.

.NET supports cross-platform cross-compilation, so Linux / macOS users may develop with Rider and debug through a Windows virtual machine.

1. Before You Start

Before setting up the environment, it is recommended to first confirm what type of changes you intend to make.

If you are only fixing documentation, adjusting configuration, or modifying a small amount of text, you usually only need to understand the basic Git commit workflow.

If you plan to modify business logic, UI behavior, core library functionality, or source generators, you need to complete a local build and perform basic testing before submitting your changes.

During development, please follow the Technical Guidelines. They include naming conventions, code style, commit message conventions, AI usage requirements, and other rules. This article will not repeat them in detail.

2. Basic Environment Requirements

This section lists the basic tools required for project development. If you are not familiar with these tools, you can continue reading the configuration instructions in the following sections.

Type	Requirement
Version control tools	Git, and GPG or SSH for commit signing
SDK toolchain	.NET SDK 10.0 or later
Runtime	.NET Desktop Runtime 8.0
Integrated development environment (IDE)	JetBrains Rider 2025.3.2 or later, or Visual Studio 2026 or later

Note

The SDK version should be equal to or higher than the version listed in the table.

The Runtime version is the fixed version required by the project. Please use the version specified in the table. A higher or lower version may not satisfy the project’s runtime requirements.

IDE Recommendation

Rider is recommended for development. If you use Visual Studio, please check your diff before submitting to avoid committing unrelated changes automatically generated by the IDE.

3. Install and Configure Git

Visit the official Git website, select Download for Windows, download the installer, and run it.

If you are not sure what the installer options mean, you can keep the default options. You can also install Git through winget with the following command:

winget install git

However, winget may use the default configuration directly, and it may not install Git Credential Manager. Unless you have special requirements, it is recommended to use the official installer first.

After installation, configure your Git username and email:

git config --global user.email your-email
git config --global user.name your-name

Email Configuration

It is recommended that user.name match your GitHub username as closely as possible, so maintainers can easily identify the source of your commits.

user.email must be an email address verified in your GitHub account. Otherwise, commit signing or identity verification may not work correctly.

Push Rejected?

If GitHub rejects your command-line push, check whether Block command line pushes that expose my email is unchecked at the bottom of the GitHub email settings page.

Submitting code through the GitHub Web Editor is not recommended. If you do need to edit online, you can use the web version of VS Code provided by GitHub, and replace PCL-Community in the URL with your own username.

4. Install the SDK and Development Environment

PCL CE depends on the .NET desktop development toolchain. The simplest way to install the required components is through Visual Studio Installer.

Click the following link to download the Visual Studio installer:

Download the Visual Studio installer

If you do not plan to install the Visual Studio IDE, you can download the Build Tools package without the IDE instead:

Download Visual Studio Build Tools

After the download is complete, run the installer. The installer will first configure Visual Studio Installer, and then automatically open the workload selection page.

In the workload list, select .NET desktop development, then click Install in the lower-right corner. After the installation is complete, your system should have the basic toolchain required to build and run PCL CE.

5. Configure Git Commit Signing

Signing Requirement

The PCL CE repository requires all commits in PRs to have verified signatures. Therefore, you need to configure commit signing locally and add the corresponding public key to your GitHub account.

This article introduces SSH signing, which is relatively simple to configure. If you prefer to use GPG signing, please refer to the GPG Signing Configuration Guide.

Generate or Confirm an SSH Key

If your user directory already contains a .ssh directory, and it contains files such as id_rsa or id_ed25519, you can use an existing key directly.

If no usable key exists, run the following command to generate a new SSH key pair:

ssh-keygen -t ed25519 -C "your-email"

The command will prompt you to enter a save location, a passphrase, and the passphrase again. If you do not need custom settings, press Enter to use the defaults.

If you set a passphrase for the key, the terminal usually will not display any characters while you type it. This is normal.

Configure Git to Use SSH Signing

Run the following commands to tell Git to use SSH as the signing format:

git config --global gpg.format ssh
git config --global user.signingkey "public-key-file-path"
git config --global commit.gpgsign true

Here, user.signingkey should be the path to the public key file. On Windows, it is recommended to use an absolute path, for example:

C:\Users\username\.ssh\id_ed25519.pub

If you do not want Git to automatically sign every commit, you can skip the third command. However, you will then need to manually add the -S parameter when committing, or enable signing separately in the Git tool you use.

Quickly Get the Path

In the .ssh directory, you can hold Shift and right-click the public key file, then select “Copy as path” to quickly obtain the absolute path to the public key file.

Note

Make sure to use the public key file with the .pub extension, not the private key file without an extension.

Also confirm again that the email configured in Git matches any verified email address in your GitHub account. Otherwise, your commits may be shown as Unverified.

Add the Signing Public Key to GitHub

Open the GitHub SSH and GPG keys settings page, then click New SSH key in the upper-right corner.

Fill in the fields as follows:

Field	Value
Title	A custom name, such as PCL CE Signing Key
Key type	Select Signing Key
Key	Enter the contents of the public key file you just generated

You can right-click the public key file and select “Edit” to open it, then copy its entire contents.

After filling in the fields, click Add SSH key to add it to your GitHub account.

6. Prepare the Local Repository

Repository Choice

If you are a community member, you can clone the community repository directly.

If you are an external developer, please fork this repository to your personal or organization account first, then clone the fork under your own account. This makes it easier to submit PRs later.

It is recommended to first create a dedicated directory for project code, for example:

C:\Projects

Then clone the repository in that directory.

If you are a community member, you can clone the main repository directly:

git clone https://github.com/PCL-Community/PCL-CE

If you are an external developer, replace the URL with the address of your own fork:

git clone https://github.com/your-username/PCL-CE

After cloning is complete, enter the repository directory:

cd PCL-CE

7. Initialize the Solution

IDE Language

It is recommended to set the IDE interface language to English. This makes it easier to look up information, communicate issues, and compare menu names with those used in this article.

When IDE options are mentioned in this article, their English names will be used first. If you use a Chinese interface, please refer to the corresponding translations yourself.

Run the following command in the repository root directory:

dotnet build

This command is used to test whether the development environment is available, and to initialize the project file structure and source generators.

If the build completes without errors, your development environment is basically ready, and you can begin development.

If the build fails, please carefully read the error message first and check whether any of the following issues exist:

• The .NET SDK or Runtime version does not meet the requirements;
• Visual Studio / Build Tools components are missing;
• NuGet package restoration failed;
• The network environment cannot access GitHub or NuGet Gallery;
• The local repository code is incomplete, or the branch state is abnormal.

If you have confirmed that there is no problem with your local environment but the project still cannot be built, a recent commit may have introduced a breaking change. In this case, you can wait for upstream updates, or discuss the issue in the community developer QQ group.

8. Basic Project Structure

PCL Community Edition is built on a Visual Studio solution (.slnx). The entire repository corresponds to one solution, which contains multiple projects.

Plain Craft Launcher 2

The main launcher project, containing most of the program logic.

This project currently includes, but is not limited to, the following:

• User interface;
• Minecraft-related management tools;
• Account authentication;
• Main launcher workflow;
• Other user-facing features.

PCL.Core

The core library of the Community Edition, containing new logic and core functionality implemented for PCL CE.

Project references are one-way: the main launcher project can reference the core library, but the core library cannot reference the main launcher project in reverse.

The core library is currently divided into different directories and namespaces by purpose. When adding new content, please place it in an existing category first. Only consider creating a new directory structure if the new content does not belong to any existing category at all.

PCL.Core.SourceGenerators

The source generator project used by the core library.

If you need to modify configuration item generation, utility code generation, or other compile-time generation logic, you will usually need to check this project.

PCL.Core.Test

The core library test project, used to check whether some implementations in the core library are correct.

If you add a core library utility, algorithm, or relatively independent logic, it is recommended to add corresponding tests in this project.

9. Start Development

After completing the local build, you can modify the code as needed.

During development, please pay attention to the following:

• Before starting development, it is recommended to create a new branch from the latest code;
• Each branch should handle only one issue or one category of changes as much as possible;
• When modifying existing files, minimize diffs unrelated to the current change;
• Code related to business logic should be basically tested locally before submission;
• For code style, naming, commit messages, and AI usage requirements, please refer to the Technical Guidelines.

If you need to add tests, you can look for similar tests in PCL.Core.Test as references.

10. Pre-commit Checklist

Before committing, it is recommended to check at least the following:

1. Whether the project can build normally.
2. Whether the modified functionality can basically run.
3. Whether there are file changes unrelated to the current modification.
4. Whether temporary files, build artifacts, or local configuration files have been committed by mistake.
5. Whether all commits have verified signatures.

You can use the following commands to view the current changes:

git status
git diff

If you use an IDE or graphical Git tool, you should also check the diff file by file before committing.

11. Commit and Push

The exact way to commit and push code varies depending on the Git tool you use. You can use the command line, Rider, Visual Studio, GitHub Desktop, or another Git client.

If you have not configured automatic signing, you need to add the -S parameter when committing:

git commit -S -m "fix(scope): fix an issue with a feature"

If automatic signing has already been configured, you can commit normally:

git commit -m "fix(scope): fix an issue with a feature"

For the commit message format, please refer to the commit message convention in the Technical Guidelines.

Branch Recommendation

It is recommended to submit changes in a new branch instead of developing directly on the default dev branch.

For example:

git checkout -b fix/some-problem

This can reduce conflicts when syncing upstream changes and opening a PR.

After committing, push the branch to GitHub:

git push origin fix/some-problem

12. Open a Pull Request

After your commits have been pushed to a branch in your GitHub repository, open the Pull Requests page and click New pull request to open a PR.

When creating the PR, please confirm the following:

• The target branch on the left is usually dev;
• The source branch on the right is the branch where you submitted your changes;
• The PR title follows the commit message convention;
• The PR description clearly explains the changes made.

It is recommended that the PR description include the following:

## Changes

- Fixed ...
- Adjusted ...
- Added ...

## Testing

- Ran `dotnet build`
- Verified locally ...

## Additional Notes

- May affect ...
- Needs to wait for ...

If the PR resolves an Issue, use a GitHub closing keyword in the PR description to link the Issue, for example:

Close #270

GitHub will automatically close the corresponding Issue after the PR is merged.

Syncing Upstream Changes

Before the PR is merged, if you need to sync upstream changes, do not use rebase or squash merge.

Please use a regular merge to avoid rewriting commit history or affecting signature status.

If you want community developers to see your PR sooner, you can request a review from PCL-Community/CE-Dev.

13. Wait for Review and Make Changes

After submitting the PR, you need to wait for review by the community developers, namely the PCL-Community/CE-Dev Team.

During the review process, maintainers may suggest changes. Please continue committing changes to the same branch according to the suggestions. The PR will update automatically.

About the Resolve Button

After addressing review comments, please do not click the Resolve button casually unless you are very sure that the issue has been fully resolved.

Resolving too early may affect the maintainer’s subsequent review. If you have explanations, questions, or additional notes, please reply directly under the corresponding comment.

After the PR passes review and meets the merge requirements, maintainers will merge it into the target branch.

Thank you for contributing to PCL CE!