Lunos
Random Uruguayan User
- 3,170
- Posts
- 16
- Years
- Montevideo (Uruguay)
- Seen yesterday
So, you have our environment set up and ready to go (WSL or MSys2) and you know the basics of building a ROM in Pokeemerald.
What should you do now? Well, you can either use a clean copy of Pokeemerald as is, or you can use a community-made project like the Pokeemerald-expansion.
Today, I'll teach you all:
Let's start with an introduction of sorts.
It was originally created by DizzyEgg and at some point, it was split into 3 Git branches (I'll talk about "branches" later), and recently, it was all merged back into a single branch.
For more information on what aspects of the game it updates, I suggest reading its readme.
Now you're ready. Let's get started.
The mere action of cloning the project using
After cloning the project and installing agbcc like you normally would when you clone a project based on Pret's GBA decomps, you're free to do whatever you want.
There's a small choice you can make and it wouldn't be fair not to talk about it.
You see, currently, the project has 2 big branches; Master which is the default branch, and Upcoming.
The difference between these is that Master acts as a Stable branch of sorts, while Upcoming acts as a Development branch.
What does this mean? That Upcoming gets every single new feature and piece of code submitted to the project first and foremost.
Only when it has all been thoroughly tested, the code is then merged into the Master branch.
Many open source projects have a Stable and a Development branch, the Master and the Upcoming branches of this project are kind of like those.
You can choose between sticking to the Master branch, or jumping to the Upcoming branch by typing
Branches this, branches that. I still haven't explained what branches are, have I?
Don't worry, I'll get there.
In the context of this tutorial, branches are a term related to Git, so before talking about them, I should talk a bit about Git in general.
Git is a version control system. It's a software that lets you manage projects of any kind, binary or code based, nice and smoothly.
It allows you to do plenty of useful things, such as storing versions/variations of your project inside "branches", or pack any changes you make to your code inside "commits".
Branches and commits are concepts heavily related to Git, they're easy to grasp.
A branch is an alternative version or a variation of your project. It's a fancy copy of it, plain and simple.
You can create a branch at any point in time by typing
Commits? Those are essentially checkpoints.
They're packs of code that contain whatever changes you make to your project.
They contain a title on the very first line, and a description in the lines below that.
You can check the list of commits inside a branch locally by using
Why did I call them "checkpoints" though? It's because they're like the checkpoints you see in any videogame.
Commits can be reverted at any point in time.
If you wanted to, you could jump back to an older commit to re-set your project to its state by the time in which the commit was made too.
The normal workflow for Git based projects starts by having you add your code changes to a pool using
That pool of changes is then turned into a commit by using
Instead of the 2 commands above, you can alternatively use
Essentially, it performs
Once you have one or more commits with changes, you can then upload your project's commits to an online repository using
You may have noticed I just mentioned a new command of sorts,
The context should have given it away, but you use
But what about "keyword"? "name_of_the_branch"?
"keyword" here refers to a GitHub repository.
Did you know you can track those? Well, now you do.
That's how you can implement community-made content into your projects.
By tracking a repository using
As for the latter, it's simple; it's quite literally the name of the branch you want to push. You can check these by typing
The branch that you're currently sitting on will be marked with a color, normally green. That's the one you'll want to push most of the time.
There's a small note I want to add here.
Do you remember how I told you that you could jump to the Pokeemerald-expansion's upcoming branch by typing
That works simply because the history of the Pokeemerald-expansion already contains the data of that branch by the time you clone it.
You can check this by typing
Alright, let us cont-
Wait a second, what is "git pull"?
It's like the opposite of
While
You have to provide a "keyword" and the "name_of_the_branch" you want to pull into your project.
This is probably a good time to mention that in order to use
After making an account there, which follows a painless process of providing a username, password and email, you need to link your account with your local copy of Git.
This is done by using
Also, the first time you try to merge in the changes from someone's repository through the usage of
There are 3 strategies, 2 of which I won't talk about because it's beyond my knowledge and/or personal experience.
I suggest you to stick to the default strategy by typing in
It is worth noting that you can move to a project's folder using
Now that I talked about
What is a merge conflict?
A merge conflict happens when you introduce changes to a file by using
It is effectively a conflict between changes in 2 different commits brought upon by the action of merging.
To spot a Merge Conflict we'll go to one of the files our terminal found a merge conflict in and then Ctrl+F "<<<<<<< HEAD".
That marks the beginning of a Merge Conflict.
Right under it we have a piece of code which is "the old code". It's what was there before our last git pull.
At some point you should be seeing a "=======" which acts as a separator. The code that comes after it is the new code brought upon by our last git pull.
What you see right after it is a ">>>>>>> (commit hash ex: f95a335c0daeba5e5f4861b7cb5eba7da685d9fa)", which marks the end of the Merge Conflict.
So, we know how to locate a merge conflict, but what should we do about it?
Well, you have to address each merge conflict individually if you want to be able to build a ROM.
As I explained above, conflicts can arise when we merge conflicting changes from 2 different commits that affect the same area/s in 1 same file.
You have to decide which piece/s of code you want to keep. The ones that were there from the start, the ones that come from the merging, or even a mix of them.
I'll present a quick example.
This is a merge conflict that used to be in the Pokeemerald-expansion back when there were still individual branches to merge.
It was happening inside the
I'll use it as an example to explain in a more direct manner how to solve a merge conflict.
The code that we see on this picture does the following process:
If the current tile's behavior allows us to trigger a surfing encounter, let's check if the Player meets the conditions to trigger a double wild battle.
If they don't, let's trigger a regular wild battle.
Then let's tell the game that this encounter was a surfing encounter, and make the snippet of code return
This entire code is a part of the
And what should we do here? 2 things.
First, we will remove the
And secondly, we will move
This way the function will enable the variable that the Dive Ball's effect needs to do its thing when it's due, and execute either a double wild battle or a regular wild battle if the correct conditions are met.
Lastly we'll delete the automatic lines introduced by Git in order to point out merge conflicts, and the result should look like this:
And that's basically how it goes.
With this, I think I covered all the basic Git commands you'll need to know about.
For anything more specific, I highly suggest reading a Git tutorial such as this one, or this one, or this one.
Don't worry, the next part of the tutorial will have practical usages of these commands.
Git is a very convenient piece of software that facilitates working with projects, as I explained above.
Just as conveniently, there's also free-to-use services that will let you upload your Git based projects online.
One of the most popular services to host a Git project on is GitHub, but there's others like GitGud or GitLab.
Now, you may be wondering...
Do I want to upload my project to an online repository?
Yes, 99% of the time, you do.
Having an online repository will facilitate many things as you work on your project.
With an online repository, people will be able see the code you decide to push there, which can be helpful not only to share features with others, but also to facilitate getting help from others too.
With an online repository, people can submit changes such as game features written by themselves in the form of Pull Requests. This makes working on projects with multiple people easier.
With an online repository, people can report you any bugs your project may have through an Issue ticket.
With an online repository, people could help you write documentation for your project inside GitHub's Wikis.
As a matter of fact, Pokeemerald has a GitHub Wiki too!
I wouldn't be surprised if there were other benefits that I can't think of right now.
So, if you think that you don't need any of these perks, feel free to leave the room; you're done. Good luck working on your project.
However, if you deem these perks juicy enough and want to benefit from them, let's go make a repository to upload your project's files there!
The first step is an obvious one; we need to make our repository.
For that, we'll open GitHub's main page, we'll hit the "+" button in the upper right corner and then click "New repository".
You will be greeted by a small page where you will have to provide a couple of details such as a name or the visibility of your repository.
Then you can also choose to initialize your repository with certain files such as a license, a README, and a .gitignore.
Having filled all the relevant data, we'll hit "Create repository" and then we'll be sent to our shiny, clean and new repository.
So, now that we have our repository, we'll need to link our local project with it so we can push our code there.
Let's move to its folder in our terminal by using the
Now, just like I explained before, we'll use
Using this command is simple,
Example of usage:
Good, and now... we just got to push our code.
Like I explained earlier, to push/upload code we have to use
In this case,
I remind you that you can check the list of branches in your repository by using
If we go back to our online repository, or press F5 if we already had it opened in our browser, we'll see after a minute at most, that our files are now visible and readable.
Congratulations, you're now the proud owner of a Git project that is hosted on the internet!
And with this, I conclude the tutorial.
If you have any questions related to the decompilation projects created by Pret, feel free to join their Discord server (invitation linked in your project's README).
A copy of this tutorial will be kept as a Gist in my GitHub account.
If I have to update this tutorial in the future, the gist will be updated as well.
https://gist.github.com/LOuroboros/c592c047ee8e8babf8a7b32713f982ad
What should you do now? Well, you can either use a clean copy of Pokeemerald as is, or you can use a community-made project like the Pokeemerald-expansion.
Today, I'll teach you all:
- How to start a project using the Pokeemerald-expansion
- About the basics of Git
- About hosting your projects online
Let's start with an introduction of sorts.
What is the Pokeemerald-expansion?
The Pokeemerald-expansion is a project created using Pokeemerald, which focuses on updating many of Pokémon Emerald's core aspects to newer standards.It was originally created by DizzyEgg and at some point, it was split into 3 Git branches (I'll talk about "branches" later), and recently, it was all merged back into a single branch.
For more information on what aspects of the game it updates, I suggest reading its readme.
Now you're ready. Let's get started.
How to start a project using the Pokeemerald-expansion?
Well, this is far easier than you might think.The mere action of cloning the project using
git clone https://github.com/rh-hideout/pokeemerald-expansion
will give you a working copy of the project's Master branch ready to use.After cloning the project and installing agbcc like you normally would when you clone a project based on Pret's GBA decomps, you're free to do whatever you want.
There's a small choice you can make and it wouldn't be fair not to talk about it.
You see, currently, the project has 2 big branches; Master which is the default branch, and Upcoming.
The difference between these is that Master acts as a Stable branch of sorts, while Upcoming acts as a Development branch.
What does this mean? That Upcoming gets every single new feature and piece of code submitted to the project first and foremost.
Only when it has all been thoroughly tested, the code is then merged into the Master branch.
Many open source projects have a Stable and a Development branch, the Master and the Upcoming branches of this project are kind of like those.
You can choose between sticking to the Master branch, or jumping to the Upcoming branch by typing
git checkout upcoming
if you want to get every single change done to the project by the time you cloned the project.About the basics of Git
Spoiler:
Branches this, branches that. I still haven't explained what branches are, have I?
Don't worry, I'll get there.
In the context of this tutorial, branches are a term related to Git, so before talking about them, I should talk a bit about Git in general.
Git is a version control system. It's a software that lets you manage projects of any kind, binary or code based, nice and smoothly.
It allows you to do plenty of useful things, such as storing versions/variations of your project inside "branches", or pack any changes you make to your code inside "commits".
Branches and commits are concepts heavily related to Git, they're easy to grasp.
A branch is an alternative version or a variation of your project. It's a fancy copy of it, plain and simple.
You can create a branch at any point in time by typing
git checkout -b name_of_your_new_branch
and it'll be like a copy of the branch you were on by the time you used the command.Commits? Those are essentially checkpoints.
They're packs of code that contain whatever changes you make to your project.
They contain a title on the very first line, and a description in the lines below that.
You can check the list of commits inside a branch locally by using
git log
on your terminal.Why did I call them "checkpoints" though? It's because they're like the checkpoints you see in any videogame.
Commits can be reverted at any point in time.
If you wanted to, you could jump back to an older commit to re-set your project to its state by the time in which the commit was made too.
The normal workflow for Git based projects starts by having you add your code changes to a pool using
git add .
.That pool of changes is then turned into a commit by using
git commit
, or alternatively, the shorter git commit -m "Write a commit title here"
.Instead of the 2 commands above, you can alternatively use
git commit -a
, or the shorter git commit -a -m "Write a commit title here"
.Essentially, it performs
git add .
subsequently followed by git commit
.Once you have one or more commits with changes, you can then upload your project's commits to an online repository using
git push keyword name_of_the_branch
.You may have noticed I just mentioned a new command of sorts,
git push
.The context should have given it away, but you use
git push
when you want to push your project's commits to a repository stored in an online Git hosting service such as GitHub.But what about "keyword"? "name_of_the_branch"?
"keyword" here refers to a GitHub repository.
Did you know you can track those? Well, now you do.
That's how you can implement community-made content into your projects.
By tracking a repository using
git remote
, you can obtain the commits that were pushed to any of its branches by using git pull
.As for the latter, it's simple; it's quite literally the name of the branch you want to push. You can check these by typing
git branch
.The branch that you're currently sitting on will be marked with a color, normally green. That's the one you'll want to push most of the time.
There's a small note I want to add here.
Do you remember how I told you that you could jump to the Pokeemerald-expansion's upcoming branch by typing
git checkout upcoming
?That works simply because the history of the Pokeemerald-expansion already contains the data of that branch by the time you clone it.
You can check this by typing
git branch -a
. This variant of git branch
will give you a full list of every single branch your project can access.Alright, let us cont-
Wait a second, what is "git pull"?
It's like the opposite of
git push
.While
git push
allows you to push or upload changes from your project to an online repository, git pull
lets you pull or incorporate changes from an online repository into your project.git pull
is used in the exact same way as git push
.You have to provide a "keyword" and the "name_of_the_branch" you want to pull into your project.
This is probably a good time to mention that in order to use
git pull
, you will need an account on the service that the repository whose branch you want to pull is hosted, which is normally GitHub.After making an account there, which follows a painless process of providing a username, password and email, you need to link your account with your local copy of Git.
This is done by using
git config --global user.name insert_your_github_username_here
and git config --global user.email insert_your_github_email_here
on your terminal.Also, the first time you try to merge in the changes from someone's repository through the usage of
git pull
, you will be asked by Git to choose the strategy that it should employ while trying to deal with conflicts on its own accord, before relaying them to you if something goes wrong.There are 3 strategies, 2 of which I won't talk about because it's beyond my knowledge and/or personal experience.
I suggest you to stick to the default strategy by typing in
git config --global pull.rebase false
and call it a day.It is worth noting that you can move to a project's folder using
cd
and remove the --global
parameter if you want to set things up on a per-project basis.Now that I talked about
git pull
, this sounds like a good time to also talk about Merge Conflicts.What is a merge conflict?
Spoiler:
A merge conflict happens when you introduce changes to a file by using
git pull
, that don't play nice with other changes already done to the same file previously.It is effectively a conflict between changes in 2 different commits brought upon by the action of merging.
To spot a Merge Conflict we'll go to one of the files our terminal found a merge conflict in and then Ctrl+F "<<<<<<< HEAD".
That marks the beginning of a Merge Conflict.
Right under it we have a piece of code which is "the old code". It's what was there before our last git pull.
At some point you should be seeing a "=======" which acts as a separator. The code that comes after it is the new code brought upon by our last git pull.
What you see right after it is a ">>>>>>> (commit hash ex: f95a335c0daeba5e5f4861b7cb5eba7da685d9fa)", which marks the end of the Merge Conflict.
So, we know how to locate a merge conflict, but what should we do about it?
Well, you have to address each merge conflict individually if you want to be able to build a ROM.
As I explained above, conflicts can arise when we merge conflicting changes from 2 different commits that affect the same area/s in 1 same file.
You have to decide which piece/s of code you want to keep. The ones that were there from the start, the ones that come from the merging, or even a mix of them.
I'll present a quick example.
![[PokeCommunity.com] About the basics of Git and starting a project with the Pokeemerald-expansion [PokeCommunity.com] About the basics of Git and starting a project with the Pokeemerald-expansion](https://media.discordapp.net/attachments/419214240277200898/773512946482544660/Untitled786.png)
This is a merge conflict that used to be in the Pokeemerald-expansion back when there were still individual branches to merge.
It was happening inside the
src/wild_encounter.c
file.I'll use it as an example to explain in a more direct manner how to solve a merge conflict.
The code that we see on this picture does the following process:
If the current tile's behavior allows us to trigger a surfing encounter, let's check if the Player meets the conditions to trigger a double wild battle.
If they don't, let's trigger a regular wild battle.
Then let's tell the game that this encounter was a surfing encounter, and make the snippet of code return
TRUE
to reiterate it.This entire code is a part of the
StandardWildEncounter
function of the src/wild_encounter.c
file, so we're also making that function return TRUE
here.And what should we do here? 2 things.
First, we will remove the
BattleSetup_StartWildBattle();
introduced by the merge.And secondly, we will move
gIsSurfingEncounter = TRUE;
putting it right above if (TryDoDoubleWildBattle())
.This way the function will enable the variable that the Dive Ball's effect needs to do its thing when it's due, and execute either a double wild battle or a regular wild battle if the correct conditions are met.
Lastly we'll delete the automatic lines introduced by Git in order to point out merge conflicts, and the result should look like this:
![[PokeCommunity.com] About the basics of Git and starting a project with the Pokeemerald-expansion [PokeCommunity.com] About the basics of Git and starting a project with the Pokeemerald-expansion](https://i.imgur.com/vPF5mcf.png)
And that's basically how it goes.
With this, I think I covered all the basic Git commands you'll need to know about.
For anything more specific, I highly suggest reading a Git tutorial such as this one, or this one, or this one.
Don't worry, the next part of the tutorial will have practical usages of these commands.
About hosting your projects online
Spoiler:
Git is a very convenient piece of software that facilitates working with projects, as I explained above.
Just as conveniently, there's also free-to-use services that will let you upload your Git based projects online.
One of the most popular services to host a Git project on is GitHub, but there's others like GitGud or GitLab.
Now, you may be wondering...
Do I want to upload my project to an online repository?
Yes, 99% of the time, you do.
Having an online repository will facilitate many things as you work on your project.
With an online repository, people will be able see the code you decide to push there, which can be helpful not only to share features with others, but also to facilitate getting help from others too.
With an online repository, people can submit changes such as game features written by themselves in the form of Pull Requests. This makes working on projects with multiple people easier.
With an online repository, people can report you any bugs your project may have through an Issue ticket.
With an online repository, people could help you write documentation for your project inside GitHub's Wikis.
As a matter of fact, Pokeemerald has a GitHub Wiki too!
I wouldn't be surprised if there were other benefits that I can't think of right now.
So, if you think that you don't need any of these perks, feel free to leave the room; you're done. Good luck working on your project.
However, if you deem these perks juicy enough and want to benefit from them, let's go make a repository to upload your project's files there!
The first step is an obvious one; we need to make our repository.
For that, we'll open GitHub's main page, we'll hit the "+" button in the upper right corner and then click "New repository".
You will be greeted by a small page where you will have to provide a couple of details such as a name or the visibility of your repository.
Then you can also choose to initialize your repository with certain files such as a license, a README, and a .gitignore.
- We know what a README is, and these projects already have one, so we don't want our repository to have one of its own.
- Software licenses are an iffy topic I won't get into. It's out of my area of expertise anyway. These projects don't use one, and you should probably keep it that way.
- Just like they have a README, these projects already have a .gitignore file, which is a file that lets you filter out specific folder paths or file attributes from your commits.
Having filled all the relevant data, we'll hit "Create repository" and then we'll be sent to our shiny, clean and new repository.
So, now that we have our repository, we'll need to link our local project with it so we can push our code there.
Let's move to its folder in our terminal by using the
cd
command if the terminal is not looking at it already.Now, just like I explained before, we'll use
git remote
to form the link.Using this command is simple,
git remote add keyword link_to_the_repository
.keyword
will be a word of your choice, any word.link_to_the_repository
should be easy to understand, it's the link to the online repository we just made.Example of usage:
git remote add myrepository https://github.com/LOuroboros/pokeemerald
.Good, and now... we just got to push our code.
Like I explained earlier, to push/upload code we have to use
git push keyword name_of_the_branch
.In this case,
git push myrepository master
, or alternatively, git push myrepository upcoming
.I remind you that you can check the list of branches in your repository by using
git branch
.If we go back to our online repository, or press F5 if we already had it opened in our browser, we'll see after a minute at most, that our files are now visible and readable.
Congratulations, you're now the proud owner of a Git project that is hosted on the internet!
And with this, I conclude the tutorial.
If you have any questions related to the decompilation projects created by Pret, feel free to join their Discord server (invitation linked in your project's README).
A copy of this tutorial will be kept as a Gist in my GitHub account.
If I have to update this tutorial in the future, the gist will be updated as well.
https://gist.github.com/LOuroboros/c592c047ee8e8babf8a7b32713f982ad
Original tutorial (outdated, only posted for archival purposes):
https://gist.github.com/LOuroboros/a6865d9ad10845085b1729faabb6dd88
Last edited: