Home

Welcome to the Golden Sun HTML5 wiki!

GSHTML5 is an engine to build games like Golden Sun 1 and 2. It's 100% open source and free (MIT licensed). Build a GS-like game without programming/hack skills.

Check the README section to see general info about the project.

Introduction for users

Once you downloaded the latest version here, extract the zip file and go to the extracted directory. In order to start the engine, just execute gshtml5.exe.

The engine content is totally controlled by what is inside resources/app/assets directory. Here you'll find tilesets, spritesheets, BGMs, SFXs, maps, and database info. On database files, you will define items, chars, NPCs, Interactable Objects, djinn, summons, etc. Any modification in this directory will automatically be reflected in the game after at least a single restart. Most of the engine data is organized through JSON files, if you're not comfortable with it, please check this tutorial What's a JSON file, it's simple.

When you download gshtml5, it already comes with the demo that's available online. Feel free to remove and keep what is relevant to your project. Please also modify as needed some initialization settings, you can check these settings here.

In order to start editing the assets to create your game, please follow some tutorials:

• Creating spritesheets with Texture Packer or Free texture packer
• Creating a simple map
• Adding NPCs to the map
• Adding Interactable Objects to the map
• Special NPCs
• Random battles
• Animated Tiles

Helpful tips for debugging your game

• Press G to enable grid mode (useful to check events position and tile numbers).
• Press D to enable collision structures debug mode.
• Find log files in gshtml5-win32-x64\resources\app\logs to check user input error.
• Press 1, 2, 3, or 4 keyboard keys to change screen size.

Introduction for developers

The project has basically two important folders: assets and base. All the source code is located inside base folder. All the game assets (images, database files, sounds, etc) are located inside assets folder. An engine user will only modify the assets folder. Any modification in assets folder files will automatically be reflected in the game after a single restart, at least.

In order to bootstrap the game, GSHTML5 uses the Phaser methods that control the game state.

GoldenSun.ts is the starting point to understand how the code works. It's the engine's main class. When the game starts, it will load database files in assets/dbs folder in order to instantiate the main classes of the game like Hero, Collision, Map, MainMenu, Audio, CursorManager etc.

For API reference, check the docs.

General class overview in game:

Here is an overview of the engine (open the image in a new tab):

What you need to know to contribute

• Have some knowledge of JavaScript or TypeScript.
• Understand minimally how Phaser 2 works.
• Played at least one time the original Golden Sun games.
• Regarding the engine, you can check the docs or ask me anything in order to make your understanding faster.

Running GS-HTML5 in your machine (developers)

• Download nodejs here
• Install it using the default configurations (if not already checked, add node.js to the system path).
• Download git here
• Install it using the default configurations (if not already checked, add git to the system path).
• Create an empty folder to store the project.
• Open your terminal and navigate to this folder:
• cd your/path/to/gshtml5
• In the terminal, type: git clone https://github.com/jjppof/goldensun_html5.git . (please note the dot in the end).
• In the terminal, type: npm install
• In the terminal, type: npm start
• The browser should open. Please wait.
• Now change anything you want in the assets folder or change the code in the base folder.

Some coding guidelines

• I strongly recommend using Visual Studio Code to develop.
• Use npm run format to format your code before your last commit when opening a PR.
• I use camel case to define types. For all the other names I use snake case.
• Avoid as much as possible using literals. Whenever you have internal states, please create an enum for holding them.
• Now the engine supports TS, so make sure you type variables as much as you can.
• Whenever creating a new class, is not a problem to pass game: Phaser.Game and/or data: GoldenSun to it in order to have easier access to game data and functionalities.
• I don't have any branching or commit comments guidelines.
• I really enjoy being verbose when giving names to variables. Please avoid using abbreviations.
• Please avoid using third-party packages with few stars in github.