Skip to content

Instantly share code, notes, and snippets.

@LOuroboros
Last active May 15, 2023 16:58
Show Gist options
  • Save LOuroboros/c592c047ee8e8babf8a7b32713f982ad to your computer and use it in GitHub Desktop.
Save LOuroboros/c592c047ee8e8babf8a7b32713f982ad to your computer and use it in GitHub Desktop.
How to start a project with the Pokeemerald-expansion
[CENTER]So, you have our environment set up and ready to go [I]([B][URL="https://www.pokecommunity.com/showthread.php?t=432351"]WSL[/URL][/B] or [B][URL="https://www.pokecommunity.com/showthread.php?t=425246"]MSys2[/URL][/B])[/I] 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 [b][url=https://github.com/rh-hideout/pokeemerald-expansion]like the Pokeemerald-expansion[/url][/b].
Today, I'll teach you all:
[list]
[*] How to start a project using the Pokeemerald-expansion
[*] About the basics of Git
[*] About hosting your projects online
[/list]
Let's start with an introduction of sorts.
[H2][B]What is the Pokeemerald-expansion?[/B][/H2]
[b][url=https://github.com/rh-hideout/pokeemerald-expansion]The Pokeemerald-expansion[/url][/b] 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 [b][url=https://github.com/DizzyEggg]DizzyEgg[/url][/b] and at some point, it was split into 3 Git branches [i](I'll talk about "branches" later)[/i], and recently, it was all merged back into a single branch.
For more information on what aspects of the game it updates, [b][url=https://github.com/rh-hideout/pokeemerald-expansion/tree/master#what-features-are-included]I suggest reading its readme[/url][/b].
Now you're ready. Let's get started.
[H2][B]How to start a project using the Pokeemerald-expansion?[/B][/H2]
Well, this is far easier than you might think.
The mere action of cloning the project using [icode]git clone https://github.com/rh-hideout/pokeemerald-expansion[/icode] will give you a working copy of the project's Master branch ready to use.
After cloning the project [b][u]and installing agbcc like you normally would when you clone a project based on Pret's GBA decomps[/u][/b], 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 [icode]git checkout upcoming[/icode] if you want to get every single change done to the project by the time you cloned the project.
[H2][B]About the basics of Git[/B][/H2]
[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 [icode]git checkout -b name_of_your_new_branch[/icode] 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 [icode]git log[/icode] 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 [icode]git add .[/icode].
That pool of changes is then turned into a commit by using [icode]git commit[/icode], or alternatively, the shorter [icode]git commit -m "Write a commit title here"[/icode].
Instead of the 2 commands above, you can alternatively use [icode]git commit -a[/icode], or the shorter [icode]git commit -a -m "Write a commit title here"[/icode].
Essentially, it performs [icode]git add .[/icode] subsequently followed by [icode]git commit[/icode].
Once you have one or more commits with changes, you can then upload your project's commits to an online repository using [icode]git push keyword name_of_the_branch[/icode].
You may have noticed I just mentioned a new command of sorts, [icode]git push[/icode].
The context should have given it away, but you use [icode]git push[/icode] when you want to [i]push[/i] your project's commits to a repository stored in an online Git hosting service such as GitHub.
[b]But what about "keyword"? "name_of_the_branch"?[/b]
"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 [icode]git remote[/icode], you can obtain the commits that were pushed to any of its branches by using [icode]git pull[/icode].
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 [icode]git branch[/icode].
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 [icode]git checkout upcoming[/icode]?
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 [icode]git branch -a[/icode]. This variant of [icode]git branch[/icode] will give you a full list of every single branch your project can access.
Alright, let us cont-
[b]Wait a second, what is "git pull"?[/b]
It's like the opposite of [icode]git push[/icode].
While [icode]git push[/icode] allows you to push or upload changes from your project to an online repository, [icode]git pull[/icode] lets you pull or incorporate changes from an online repository [i]into[/i] your project.
[icode]git pull[/icode] is used in the exact same way as [icode]git push[/icode].
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 [icode]git pull[/icode], you will need an account on the service that the repository whose branch you want to pull is hosted, which is normally GitHub.
After [url=https://github.com/join][b]making an account there[/b][/url], 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 [icode]git config --global user.name insert_your_github_username_here[/icode] and [icode]git config --global user.email insert_your_github_email_here[/icode] on your terminal.
Also, the first time you try to merge in the changes from someone's repository through the usage of [icode]git pull[/icode], 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 [icode]git config --global pull.rebase false[/icode] and call it a day.
[i]It is worth noting that you can move to a project's folder using [icode]cd[/icode] and remove the [icode]--global[/icode] parameter if you want to set things up on a per-project basis.[/i]
Now that I talked about [icode]git pull[/icode], this sounds like a good time to also talk about [B][U]Merge Conflicts[/U][/B].
[B]What is a merge conflict?[/B]
[spoiler]
A merge conflict happens when you introduce changes to a file by using [icode]git pull[/icode], 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 "[B]<<<<<<< HEAD[/B]".
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 "[B]=======[/B]" 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 "[B]>>>>>>> [I](commit hash ex: f95a335c0daeba5e5f4861b7cb5eba7da685d9fa)[/I][/B]", 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.
[IMG]https://media.discordapp.net/attachments/419214240277200898/773512946482544660/Untitled786.png[/IMG]
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 [icode]src/wild_encounter.c[/icode] 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 [icode]TRUE[/icode] to reiterate it.
This entire code is a part of the [icode]StandardWildEncounter[/icode] function of the [icode]src/wild_encounter.c[/icode] file, so we're also making that function return [icode]TRUE[/icode] here.
And what should we do here? 2 things.
First, we will remove the [icode]BattleSetup_StartWildBattle();[/icode] introduced by the merge.
And secondly, we will move [icode]gIsSurfingEncounter = TRUE;[/icode] putting it right above [icode]if (TryDoDoubleWildBattle())[/icode].
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:
[img]https://i.imgur.com/vPF5mcf.png[/img]
And that's basically how it goes.
[/spoiler]
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 [b][url=https://www.atlassian.com/git/tutorials]this one[/url][/b], or [b][url=https://git-scm.com/docs/gittutorial]this one[/url][/b], or [b][url=https://www.w3schools.com/git/git_intro.asp?remote=github]this one[/url][/b].
Don't worry, the next part of the tutorial will have practical usages of these commands.
[/spoiler]
[H2][B]About hosting your projects online[/B][/H2]
[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 [url=https://github.com/][b]GitHub[/b][/url], but there's others like [b][url=https://gitgud.io/]GitGud[/url][/b] or [b][url=https://gitlab.com/dashboard/projects]GitLab[/url][/b].
Now, you may be wondering...
[b]Do I want to upload my project to an online repository?[/b]
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 [url=https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues][b]an Issue ticket[/b][/url].
With an online repository, people could help you write documentation for your project [url=https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis][b]inside GitHub's Wikis[/b][/url].
[i]As a matter of fact, [url=https://github.com/pret/pokeemerald/wiki][b]Pokeemerald has a GitHub Wiki too[/b][/url]![/i]
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 [url=https://github.com/][b]GitHub's main page[/b][/url], 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.
[list]
[*]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.
[/list]
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 [icode]cd[/icode] command if the terminal is not looking at it already.
Now, just like I explained before, we'll use [icode]git remote[/icode] to form the link.
Using this command is simple, [icode]git remote add keyword link_to_the_repository[/icode].
[icode]keyword[/icode] will be a word of your choice, any word.
[icode]link_to_the_repository[/icode] should be easy to understand, it's the link to the online repository we just made.
Example of usage: [icode]git remote add myrepository https://github.com/LOuroboros/pokeemerald[/icode].
Good, and now... we just got to push our code.
Like I explained earlier, to push/upload code we have to use [icode]git push keyword name_of_the_branch[/icode].
In this case, [icode]git push myrepository master[/icode], or alternatively, [icode]git push myrepository upcoming[/icode].
I remind you that you can check the list of branches in your repository by using [icode]git branch[/icode].
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!
[/spoiler]
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 [i](invitation linked in your project's README)[/i].
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.
[url]https://gist.github.com/LOuroboros/c592c047ee8e8babf8a7b32713f982ad[/url]
[/CENTER]
[I]Original tutorial [I](outdated, only posted for archival purposes)[/I]:
[url]https://gist.github.com/LOuroboros/a6865d9ad10845085b1729faabb6dd88[/url][/I]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment