[Pokeemerald] About the basics of Git and starting a project with the Pokeemerald-expansion

Lunos · Mar 13, 2020

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:

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.

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:

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

Splitnonemore · Mar 28, 2020

So now I have a pokemon emerald game with updated movesets? Nice thank you

felipenx · Apr 6, 2020

Thanks a lot! This tutorial really helpme. I can finally doit rigth

Spoiler:

Cyrus CapoGalassia · Apr 9, 2020

Thanks a lot for the tutorial. I have only one problem that I don't know how to fix since I'm new. I can't finish to build the ROM because of this. It's already the second time that this happens to me and it stays like this for a long time, like 2 hours, resulting in me not being able to build the ROM. I was wandering if this was normal or, if I made something wrong, how to fix this😅. Thank you again for this amazing tutorial.
Here's what I'm talking about:

Spoiler:

cd build/emerald && sed "s#tools/#../../tools/#g" ../../ld_script.txt > ld_script.ld

Lunos · Apr 9, 2020

Cyrus CapoGalassia said:
Thanks a lot for the tutorial. I have only one problem that I don't know how to fix since I'm new. I can't finish to build the ROM because of this. It's already the second time that this happens to me and it stays like this for a long time, like 2 hours, resulting in me not being able to build the ROM. I was wandering if this was normal or, if I made something wrong, how to fix this😅. Thank you again for this amazing tutorial.
Here's what I'm talking about:

Spoiler:

cd build/emerald && sed "s#tools/#../../tools/#g" ../../ld_script.txt > ld_script.ld

That's... not really an error? Not by itself anyway.
Could you please post a screencap of your terminal/shell, or be more specific about the error?

Cyrus CapoGalassia · Apr 9, 2020

Lunos said:
That's... not really an error? Not by itself anyway.
Could you please post a screencap of your terminal/shell, or be more specific about the error?

Oh, sorry. Here's the screen:

Spoiler:

Lunos · Apr 9, 2020

Cyrus CapoGalassia said:
Oh, sorry. Here's the screen:

Spoiler:

https://i.imgur.com/PywkNfo.png

That's not really an error, it's just a part of the building process.

Cyrus CapoGalassia · Apr 9, 2020

Lunos said:
That's not really an error, it's just a part of the building process.

Ok, thanks for your help. I don't know why, but everytime I get to that part it stops. I waited all day but nothing happened. Guess I'll try again😅. Thanks again!

Lunos · Apr 9, 2020

Cyrus CapoGalassia said:
Ok, thanks for your help. I don't know why, but everytime I get to that part it stops. I waited all day but nothing happened. Guess I'll try again??????. Thanks again!

Try doing a few left clicks on the window or its title bar. Sometimes the terminal/shell may look inactive, but it's actually working normally without updating the text log in the window.
I don't know why is that, but it has happened to me a few times.

Cyrus CapoGalassia · Apr 9, 2020

Lunos said:
Try doing a few left clicks on the window or its title bar. Sometimes the terminal/shell may look inactive, but it's actually working normally without updating the text log in the window.
I don't know why is that, but it has happened to me a few times.

Ok, I'll try. Thanks for your patience.

Diego Mertens · Apr 12, 2020

So, i've made some changes to my project, but when I make the "git push ORIGIN master" thing, it says everything is up-to-date, but it isn't. How do I commit my changes?

Lunos · Apr 12, 2020

Diego Mertens said:
So, i've made some changes to my project, but when I make the "git push ORIGIN master" thing, it says everything is up-to-date, but it isn't. How do I commit my changes?

You haven't provided enough information so it's hard for me to help you, but I encourage you to read the 3rd section of the main post again.

If you tried to make changes to files, and then git push just like that, you're doing it wrong.

Diego Mertens · Apr 12, 2020

Lunos said:
You haven't provided enough information so it's hard for me to help you, but I encourage you to read the 3rd section of the main post again.

If you tried to make changes to files, and then git push just like that, you're doing it wrong.

Yes, I read it, and I have made a lot of changes, in graphics, h and c files, that kind of stuff. Then I saved them, I came to here for seeing how to commit my changes, and then I did the git push thing.
But, how do I update my repository then? I tried the git push thing, but it does nothing, I tried with a new branch, but it doesn't work (obviously), so, what do I have to do for updating it?

Lunos · Apr 12, 2020

Diego Mertens said:
Yes, I read it, and I have made a lot of changes, in graphics, h and c files, that kind of stuff. Then I saved them, I came to here for seeing how to commit my changes, and then I did the git push thing.
But, how do I update my repository then? I tried the git push thing, but it does nothing, I tried with a new branch, but it doesn't work (obviously), so, what do I have to do for updating it?

If you made a commit properly and then tried to push it, make sure you're pushing it to the same branch where you're on.
You can check your current branch by using git branch.
You can't push commits to a branch called master if you're not in a branch with the same name.

Martinii93 · Apr 22, 2020

Hey I've been working with Dizzy's works for a bit now and it all went fluently until now, I just added a couple of moves in LEVEL_UP_LEARNSETS and edited a few types and abilities in BASE_STATS; but now i get these errors;
What did I do wrong?

Spoiler:

What can I do to fix this?

DizzyEgg · Apr 24, 2020

Martinii93 said:
Hey I've been working with Dizzy's works for a bit now and it all went fluently until now, I just added a couple of moves in LEVEL_UP_LEARNSETS and edited a few types and abilities in BASE_STATS; but now i get these errors;
What did I do wrong?

Spoiler:

What can I do to fix this?

Hard to say from the log alone, could you copy the contents of the mentioned files to pastebin and post them here?

Martinii93 · Apr 24, 2020

It just accidentally deleted one "}" when editing an ability so it seems but didn't find it immediately , very frustrating!
But now I managed to fix it :p !
But thanks anyway, and thank you for your hard work and help, Dizzy! (and Lunos.. and everyone else involved with the disassembly projects).
It really is much more convenient to work with than binary hacking.

ShinyVolcanion_ · Apr 27, 2020

If i wanted to add another pokeemerald thing like follow me (by
ghoulslash)what would i do and where/when would i add it

Lunos · Apr 27, 2020

ShinyVolcanion_ said:
If i wanted to add another pokeemerald thing like follow me (by
ghoulslash)what would i do and where/when would i add it

If you read the main post, you'll learn how.

PokemonCrazy · May 10, 2020

I followed this tutorial as closely as possible, but I keep getting a build error. I've tried and retried about 3 times now, but it still doesn't work, it just stops after the last line in this quote.

arm-none-eabi-as -mcpu=arm7tdmi --defsym MODERN=0 -o build/emerald/src/mail.o build/emerald/src/mail.s
tools/gbagfx/gbagfx.exe graphics/unknown/unknown_58E82C.pal graphics/unknown/unknown_58E82C.gbapal
arm-none-eabi-as -mcpu=arm7tdmi --defsym MODERN=0 -o build/emerald/src/battle_util.o build/emerald/src/battle_util.s
tools/gbagfx/gbagfx.exe graphics/interface/hold_icons.png graphics/interface/hold_icons.4bpp
make: *** [Makefile:252: build/emerald/src/pokemon.o] Error 1
make: *** Waiting for unfinished jobs....
arm-none-eabi-as -mcpu=arm7tdmi --defsym MODERN=0 -o build/emerald/src/librfu_intr.o build/emerald/src/librfu_intr.s
arm-none-eabi-as -mcpu=arm7tdmi --defsym MODERN=0 -o build/emerald/src/script_pokemon_util_80F87D8.o build/emerald/src/script_pokemon_util_80F87D8.s
arm-none-eabi-as -mcpu=arm7tdmi --defsym MODERN=0 -o build/emerald/src/battle_gfx_sfx_util.o build/emerald/src/battle_gfx_sfx_util.s

EDIT: I was able to get it to build with no issues after removing pokemon_expansion.

[Pokeemerald] About the basics of Git and starting a project with the Pokeemerald-expansion

More options

Lunos

Random Uruguayan User

What is the Pokeemerald-expansion?

How to start a project using the Pokeemerald-expansion?

About the basics of Git

About hosting your projects online

Splitnonemore

felipenx

Cyrus CapoGalassia

Lunos

Random Uruguayan User

Cyrus CapoGalassia

Lunos

Random Uruguayan User

Cyrus CapoGalassia

Lunos

Random Uruguayan User

Cyrus CapoGalassia

Diego Mertens

Lunos

Random Uruguayan User

Diego Mertens

Lunos

Random Uruguayan User

Martinii93

DizzyEgg

Martinii93

ShinyVolcanion_

VibeCheck

Lunos

Random Uruguayan User

PokemonCrazy