Gecko2D

Getting Started

To use Gecko2D you need Git and Node.js 9.x.x or higher.

Installation

Just install it via npm:

npm install gecko2d -g

You can test it typing in your terminal gecko init -t flappy watch and going to http://localhost:8080 to play a flappy bird clone.

First Steps

Initialize

You can start a new project typing in your terminal gecko init on an empty folder or gecko init -t empty, this will clone the structure from the template basic or empty, and create the config file dev.gecko.toml.

Project structure

Every project has this structure by default:

  • Assets: A directory to add the game images, sounds, etc...
  • Libraries: Plugins goes here.
  • Sources: Where the magic happends, the source code of your game.
  • dev.gecko.toml: This is the project's config file, read more on his section.
  • khafile.js: Kha's config, this file is autogenerated and (normally) you don't need to change it.

Build and serve

To build the game use gecko build. By default the build command will create a html5 bundle, you can serve it on http://localhost:8080 using gecko serve. To build and serve automatically when some source change use gecko watch.

Command Line Interface

Gecko has a command line interface to make your life easy.

  • gecko init [ -t template ]: initialize a new project.
  • gecko build [ target ] [ -c config ]: compile the current project.
  • gecko watch [ -c config ]: watch the project and serve the changes.
  • gecko serve [ -c config ]: serve the html5 build.
  • gecko dir [ -kha ]: print the directory where gecko (or kha) is intalled.
  • gecko khafile [ -c config ]: generate the khafile.js using the config file.
  • gecko docs: serve the documentation at 8081

Type gecko help in your terminal for more information.

IDEs

You can use any IDE with support for haxe, but, in this guide we'll cover Kode Studio.

Kode Studio

Kode Studio is a fork of Visual Studio Code with everything you will need to work in a Kha's project, as haxe support, intellisense and debugging features.

If it's good for Kha, it's good for Gecko2D. Kode Studio needs a config file named khafile.js, this file is generated by default when a new gecko's project is initiated, you just need to open your project with Kode Studio and work on it.

Kode Studio includes his own version of Kha, if you want to compile your project using the compilation options of Kode Studio is better use the version of Kha which include gecko, to do that typing in your terminal gecko dir -kha and copy the returned directory, go to Kode Studio -> Preferences and set kha.khaPath with the directory copied.

Check the start and buildsection of Kha to know more about Kode Studio, and how debug your project with it.

Config file

Every project use a file named dev.gecko.toml as a config file. This file is used to generate the khafile.js before the compilation.

The config file is basically an abstraction of the khafile.js with some extra options. This file defines parameters to compile to differents targets, and how the project is structured.

# development gecko config.
name = "Gecko2D-Game"
sources = ["Sources"]
shaders = []                        #shaders directory
libraries = []                      #libs at Libraries folder or haxelib
output = "build"                    #build output
debug = false                        #compile in debug mode

[html5]
webgl = true
canvas = "kanvas"           #canvas id
script = "game"             #script name
serve_port = 8080           #port to serve the build with gecko serve
html_file = ""              #inject the script in a custom html

[osx]
graphics = "opengl"         #mac graphics [opengl | metal]

[windows]
graphics = "direct3d11"         #windows graphics [direct3d11 | direct3d9 | direct3d12 | opengl]

[flags]                         #custom compiler flags
#debug_collisions = true

[core]
clean_temp = false              #clean temporal files after compile
compile = false                 #if false, the game will not be compiled, and the "resources" to compile will stay at the build directory
compiler_parameters = []        #haxe compiler parameters (ex: "-dce full")
ffmpeg = ""                     #ffmpeg drivers path (could be absolute)
haxe = ""
kha = ""

If your are building your project using Kode Studio, and you change something in your config file, use gecko khafile to update the project's khafile.js. If you're using gecko build [ target ] to build the project the khafile.js will be updated automatically.

Building a project

To build your project, type in your terminal gecko build [ target ] where target is the platform you want. This is going to create the files to debug or compile the project. If the dev.gecko.toml -> core -> compile is true, Kha will try to compile your project directly.

HTML5

This is the easiest platform to build, nothing extra is required, just use gecko build and the build goes to the path build/html5-build. If dev.gecko.toml -> debug is false, the javascript bundle will be minificated.