{"id":18928616,"url":"https://github.com/darkkodkod/gbatool","last_synced_at":"2026-01-18T09:03:01.332Z","repository":{"id":184697391,"uuid":"672319807","full_name":"DarkKodKod/GBATool","owner":"DarkKodKod","description":"Tool to create and manage assets for a Game Boy Advance game.","archived":false,"fork":false,"pushed_at":"2026-01-13T23:23:39.000Z","size":7869,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-14T01:29:10.824Z","etag":null,"topics":["csharp","gba","gba-dev","gba-development","retro","wpf","wpf-application","wpf-ui"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DarkKodKod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-29T17:05:30.000Z","updated_at":"2026-01-13T23:23:42.000Z","dependencies_parsed_at":"2026-01-04T12:04:29.908Z","dependency_job_id":null,"html_url":"https://github.com/DarkKodKod/GBATool","commit_stats":null,"previous_names":["darkkodkod/gbatool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DarkKodKod/GBATool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkKodKod%2FGBATool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkKodKod%2FGBATool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkKodKod%2FGBATool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkKodKod%2FGBATool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DarkKodKod","download_url":"https://codeload.github.com/DarkKodKod/GBATool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkKodKod%2FGBATool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","gba","gba-dev","gba-development","retro","wpf","wpf-application","wpf-ui"],"created_at":"2024-11-08T11:26:44.137Z","updated_at":"2026-01-18T09:03:01.325Z","avatar_url":"https://github.com/DarkKodKod.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GBATool\nTool written in C# and WPF using the MVVM design pattern to create and manage asset for a Game Boy Advance game by Felipe Reinaud. Resources files are in TOML format, [https://github.com/toml-lang/toml](https://github.com/toml-lang/toml). \n\n### Table of Content  \n[1. Overview](#Overview)   \n[1.1. Menu](#Menu)   \n[1.2. Toolbar](#Toolbar)   \n[2. Getting started](#Gettingstarted)   \n[2.1 Project Properties](#ProjectProperties)   \n[2.2 Create project elements](#CreateElements)   \n[3. Managing resources](#ManagingResources)   \n[3.1. Tile Sets](#TileSets)   \n[3.2. Banks](#Banks)   \n[3.3. Characters](#Characters)   \n[3.4. Palettes](#Palettes)   \n[4. Building the project](#Buildingtheproject)   \n[4.1. Building for Butano](#Buildingforbutano)   \n\n\u003ca name=\"Overview\"/\u003e\n\n## 1. Overview\n\nThe purpose of this tool is to provide a way to create and manage Game Boy Advance assets that is game agnostic. This means that the tool will not restrict what can be created with the original hardware. Assets can have any configuration, and the software/game will add the necessary limitations for them to run properly. Another goal is to have a single executable file that runs without depending on external files, like DLLs. This executable is self-contained, which is why it is so large. With this tool, you can import sprite sheets and organize images to create character blocks, palettes, character animations, and more. For now, the current features are all I need for my game, but if you would like to contribute to expanding its capabilities to export different file formats, please let me know.\n\n![](/Images/gbatool.png)\n\n\u003ca name=\"Menu\"/\u003e\n\n### 1.1 Menu\n\n![](/Images/menu.png)\n\n#### File\n![](/Images/file_menu.png)\n\nFrom File is possible to create a new project or a new element like a [Tile Sets](#TileSets) or a [Character](#Characters).\n\n* A new project will have the extension **.proj** which is internaly a [TOML](https://github.com/toml-lang/toml) format and the name is given by the user. It will also create the folders **Banks**, **Palettes**, **Characters** and **TileSets**. \n\n* You can open an existing project, where the **.proj** file exist.\n\n* Close the current project.\n\n* Import any image from these formats: *.png, .bmp, .gif, .jpg, .jpeg, .jpe, .jfif, .tif, .tiff, .tga*. The image will reduce the colors with a Palette Quantizer algorithm to match the number of colors the NES can reproduce. More about this topic in the [Getting started](#Gettingstarted).\n\n* Recent project will contain all previous opened projects.\n\n#### Edit\n![](/Images/edit_menu.png)\n\nUndo/Redo, Copy, Paste, Duplicate and Delete only affects the project's elements like a [Character](#Characters) element.\n\n#### Project\n![](/Images/project_menu.png)\n\n* Project Properties is where is possible to reconfigure the project settings after the project is created. There are actually more options here change than when the project is created. For more information read the [Getting started](#Gettingstarted) section.\n\n* Build Project will create and export all maps, characters and pattern tables in the selected output folder. More on that in [Building the project](#Buildingtheproject) section.\n\n#### Help\n![](/Images/help_menu.png)\n\nView Help redirects to this page in github.com.\n\n\u003ca name=\"Toolbar\"/\u003e\n\n### 1.2 Toolbar\n\n![](/Images/toolbar.png)\n\nToolbar Has the option to create a new project (explained in [Getting started](#Gettingstarted) section) or open an existing project, undo or redo (not recommended to use) and build project. The last one is explained in the [Building the project](#Buildingtheproject) section.\n\n\u003ca name=\"Gettingstarted\"/\u003e\n\n## 2. Getting started\n\nOnce GBATool is opened for the first time, it will create in the root of the executable, the file **config.toml**, but only if some of the configuration of the tool changes like the window size.\n\n![](/Images/newproject.png)\n\nTo craete a new project click File \u003e New \u003e New Project (Ctrl + Shift + N) or ![](/Images/newproject_toolbar.png) in the toolbar. From there is possible to name the project and a location. After the button *Create project* is pressed it will create at the specified location the file *name of the project*.proj in [TOML](https://github.com/toml-lang/toml) format, and the folders *Banks*, *Characters*, *TileSets*.\n\nGBATool will always open the last opened project. \n\n\u003ca name=\"ProjectProperties\"/\u003e\n\n### 2.1 Project Properties\n\nAt any time is possible to change the project configurations from the menu Project \u003e Project Properties...\n\n![](/Images/projectproperties.png)\n\nFrom Project properties it is possibled to set up the output format for each type of asset. The Game Boy Advance header can exported in assembly language, same as the palettes and the character's animation data. The Screen Blocks are exported in binary format for example. The *Game Properties* is the information that is used to generate the Game Boy Advance header. The *Sprite Pattern Format* can be 1D or 2D. This is how the internal character blocks are arranged when exported.\n\n\u003ca name=\"CreateElements\"/\u003e\n\n### 2.2 Create project elements\n\n![](/Images/newelement.png)\n\nCreating elements is possible from the menu File \u003e New \u003e New Element (Ctrl + N) or right click on any root folder to open the context menu and select *Create New Element*.\n\nThere are only four type of elements to create, [Tile Sets](#TileSets), where you can import a new image and change its pixels, [Banks](#Banks), where you can create banks of any size or NES pattern tables using the [Tile Sets](#TileSets) as input, [Palettes](#Palettes), are the actual colors for any sprite used by the caracteres, [Characters](#Characters), is an element created by [Banks](#Banks) as its input and there, it is possible to create meta sprites and animations. It is really important to understand that all of the links between elements are just references to each other. For example: the bank pattern table could use different tile sets but if one of those tile sets changes something it will also change the tile inside the pattern table and immediately in the character or map that is using that specific bank.\n\n![](/Images/tree.png)\n\nIs possible to create folders inside each root folder and move elements of the same type to any sub folder by just dragging the element. Each element including folders has a context menu with the right click.\n\nTo start creating assets for the Game Boy Advance, the very first thing to create is the Tile Set explained in the section below.\n\n\u003ca name=\"ManagingResources\"/\u003e\n\n## 3. Managing resources\n\n\u003ca name=\"TileSets\"/\u003e\n\n### 3.1 Tile Sets\n\nTile Sets are the basic element to start constructing Game Boy Advance assets but they are not exported directly, they are only used to build [Banks](#Banks), those can be exported from this tool. This is explained more in depth in the [Building the project](#Buildingtheproject) section. Tile Sets are images from these formats: *.png, .bmp, .gif, .jpg, .jpeg, .jpe, .jfif, .tif, .tiff, .tga*. Once is imported, it is possible to define sprite areas in all supported sizes like 8x8, 16x16, 32x32, 64x64, 16x8, 32x8, 32x16, 64x32, 8x16, 8x32, 16x32 and 32x64. This sprites are later used to construct a character meta sprite including its animation.\n\n![](/Images/Axl.png)\n\nLet´s use this image from Final Fight One as an example for later steps.\n\n![](/Images/importimage.png)\n\nThere are two ways to import a new image to a *Tile Set* element, first one is to use File \u003e Import \u003e Image... (Ctrl + I). This will create a *Tile Set* element with the name of the image. The second way to import an image is to create a *Tile Set* element, explained the the [Getting started](#Gettingstarted) section and then click over the new element and then click the *tree dots* button on the top part of the element window to browse your computer for an image.\n\nAll images after being imported will create if it doesn't exist already a folder name **Images** in the project root directory and I will copy the new imported image there with the extension *.bmp*.\n\n![](/Images/importedimage.png)\n\nAfter the image is imported it is possible to zoom in/out with the mouse's scroll wheel and you can pick one of the crop sizes to select what part of the entire image you want to create a sprite of that. Then an sprite will appear in the box to the right. There is possible to delete it if not needed.\n\n![](/Images/sprites_alias.png)\n\nThe field **Alias** is assigned automatically to any new sprite created. The alias can be changed to any string value. This is later used by the [Banks](#Banks) to ideantify the sprites if is needed.\n\n\u003ca name=\"Banks\"/\u003e\n\n### 3.2 Banks\n\nBanks are tiles grouped together. Is possible to have banks arraged in 1D or 2D (When the checkbox **Is Background** is checked then it will always be 1D arragement). These charblocks can be used either for background or sprites. The source of these banks are constructed from [Tile Sets](#TileSets). This will form a link inside the banks to each **Tile Set** used. If a Tile Set changes its tiles, it is renamed or removed, it will automatically update the bank. From here is possible to generate a [Palette](#Palette) object but these are not linked together. The link is done in the [Character](#Character) object. If your bank is using more than 16 colors then it is important to check the checkbox 256 colors, then when a palette is constructed, it will create palettes objects as much as needed up to 16 palette objects. To have the first color of the palette with the transparency color, click on any sprite region here and by pressing the button **Obtain Transparent Color** it will store the very first pixel of that sprite region.\n\n![](/Images/bank.png)\n\nWhen building the project, see: [Building the project](#Buildingtheproject), it will generate bank files for each bank object in the project.\n\n\u003ca name=\"Characters\"/\u003e\n\n### 3.3 Characters\n\nCharacters are created by using banks. The tiles from this bank will be stored as a link to them, if one of those banks changes, it is renamed or deleted it will automatically updates the character.\n\n![](/Images/emptyCharacter.png)\n\nPress the plus button in the tab to create a new animation.\n\n![](/Images/character.png)\n\nFrom here it is possible to create frames for the animation. Clicking the plus button will create a new frame of the animation. When there is more than one frame, the play button, stop, pause, previous frame and next frame are available.\n\nHere is also possible to set the animation speed. This value is in seconds per frame and this is also used when building the project to be used in the output file. More details explained in [Building the project](#Buildingtheproject) section.\n\n![](/Images/edit_frame.png)\n\nScene position area is just for export the correct position only, **Relative Origin** are the yellow lines, this is used to calculate the origin where every x and y position is calculated so it is used as the 0,0 where the lines are. **Vertical Axis** is the red line and it is used as the center of the sprite. It is used to calculate the flip position of all the sprites and **Base** it is the position for the feets. This is the only one that it is exported because it could be used as a visual feet position for somme collisions or z sorting for example.\n\nDemo of the sprites in motion from Mesen's Sprite Viewer.\n\n![](/Images/demo1.gif)\n\n\u003ca name=\"Palettes\"/\u003e\n\n### 3.4 Palettes\n\nHere it is just simply, a 16 colors palette where is possible to pick and change the colors. This palettes are referenced by name for the [Characters](#Characters). It is required to link the palette with a character so the character can be exported.\n\n![](/Images/palette.png)\n\n\u003ca name=\"Buildingtheproject\"/\u003e\n\n## 4. Building the project\n\n![](/Images/build.png)\n\nBuilding the project will create a bunch of files in the output directory:\n\n+ For each [Bank](#Banks) element, it will generate a .bin file.\n+ An .asm file containing all the [Palette](#Palettes) elements called **palettes.asm**.\n\nExample of the assembly output file for Palettes:\n```\n; This file is auto generated!\n\n; Color format: RGB555 0BBBBBGGGGGRRRRR\n\n    align 32\npalette_axl:\n    db 0xF7,0x67,0xAD,0x04,0x1A,0x3E,0x33,0x25,0xDF,0x56,0x6E,0x0C,0x12,0x0D,0xAD,0x31,0x29,0x21,0xA5,0x10,0x28,0x04,0xFF,0x56,0x9C,0x63,0x73,0x46,0xF7,0x56,0x00,0x00\npalette_guy:\n    db 0x00,0x42,0x31,0x04,0x1D,0x00,0x35,0x04,0x29,0x04,0xCD,0x04,0xBF,0x07,0x93,0x19,0x5E,0x02,0xF7,0x7A,0xFF,0x7F,0x17,0x2A,0x7E,0x2E,0xFF,0x36,0x7F,0x01,0x00,0x00\n```\n \n+ A header file.\n+ Character files for their animations.\n\n\u003ca name=\"Buildingforbutano\"/\u003e\n\n### 4.1. Building for Butano\n\nGo to project properties from the menu or by pressing Ctrl+P to open the Project Properties dialog and set Butano for **Palettes**, **Characters**, **Screenblock**. For **Header** set it to None.\n\n![](/Images/projectproperties.png)\n\nSet the cpp and header folder to the correct place on your folder and then after building the project by pressing F5 or clicking Build Project from the menu.\n\nThis will generate cpp and header files with classes to handle meta sprites and its animations.\n\nHere as an example the exported class is called **gbatool::Guy**, This one is a class that act as a meta sprite with its own sprite that can all be animated by calling the method, **load_animation**. The animation IDs are defined inside the class and those comes from the **GBATool** itself when you create [Characters](#Characters).\n\nHeader file example:\n```\nclass title : public scene\n{\npublic:\n    title(bn::camera_ptr camera);\n    void update();\n\nprivate:\n    bn::unique_ptr\u003cgbatool::Guy\u003e _player;\n}\n```\n\ncpp file example:\n```\ntitle::title(bn::camera_ptr camera)\n{\n    _player.reset(new gbatool::Guy());\n    _player-\u003eset_camera(camera);\n    _player-\u003eload_animation(gbatool::Guy::AnimationID::WALKING);\n    _player-\u003eset_position(bn::fixed_point(0, 0));\n}\n\nvoid title::update()\n{\n    _player-\u003eupdate_animation();\n}\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkkodkod%2Fgbatool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkkodkod%2Fgbatool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkkodkod%2Fgbatool/lists"}