README
¶
TGE - Portable Runtime in GO
TGE aims to provide a light, portable and unopiniated runtime to integrate your favorite Go libraries (at least mines) to portable applications (dektop, web & mobile) and package them in a proper way (not a mere executable).
TGE is not and should not be another new game engine but instead a way to focus on business code and not low level pipes and hacks. The core is intended to be as light as possible and depends on plugins to enable cool features (OpenGL, AL, Vulkan, GUI...)
TGE runtime benefits from power ful channels paradigm of Go to propose rendering across 2 synchronized loops Ticker and Render:
See it in action in tge-examples and look below for more details.
An online demo (Work in Progress) is also available here : http://tge-demo.thommil.com
TGE Core
Core implements a minimal runtime for several platforms:
- Windows, MacOS & Linux
- Android 5+ & IOS 8+
- Web on Chrome, Firefox & Safari
TGE plugins
Plugins allow to create your game/application by choosing implementation for different parts (GUI, rendering, sound...). This way, you choose how to create your game/application. I'm trying to port as many features as I can in plugins, natively portable libraries are off course directly usable too (physics, AI...).
| Plugin link | Details |
|---|---|
| tge-gesture | Gestures for touch screens with support for Android, IOS and mobile browsers. Implements longpress, swipe and pinch gestures. |
| tge-gl | OpenGL/ES 3+ API based on go-gl work. Expose OpenGL to App in a portable way, il you want a low level access to the graphical context. Needed by most graphical libraries and plugins. |
| tge-g3n | Based on the awesome G3N game engine written in Go. This great piece of software engineering is brought to Mobile and Web by TGE. |
| tge-audio | Audio support based on Web Audio API. Brings full support for sound effects and spacialization with a comprehensive API ;) |
Getting started
Based on what is done with tools like Vue.js, Node or Spring, TGE offers a command line tool tge-cli to ease creation and build of TGE applications.
Install tge-cli
To get the client, run:
go get github.com/thommil/tge-cli
The command line tool should be available in the $GOPATH/bin folder.
Create new application
The create a new application workspace, run:
tge-cli init [package-name]
An application folder will be created with all needed resources to begin. See tge-cli and Go Doc for details and API.
Build the application
Once the application folder is created, releases can be generated using:
tge-cli build -target [target] [package-path]
Target allows to build your application for Desktop, Mobile or Web backend. See tge-cli for full details on how to use it and customize each target.
Coding
Applications
App is the main entry point of a TGE application. The code below is generated by tge-cli when creating a new project:
package main
import (
"time"
// Runtime package
tge "github.com/thommil/tge"
//Available plugins - Just uncomment to enable
//gesture "github.com/thommil/tge-gesture"
//gl "github.com/thommil/tge-gl"
//g3n "github.com/thommil/tge-g3n"
)
// App instance context and definition
type App struct {
// Put global attributes of your application here
}
// OnCreate is called at App instanciation, the Runtime resources are not
// yet available. Settings and treatments not related to Runtime should be done here.
func (app *App) OnCreate(settings *tge.Settings) error {
// Settings is passed as a pointer can be modified to adapt App to your needs
// Ex :
// settings.Name = "My Awesome App++"
// settings.Fullscreen = true
// settings.EventMask = tge.AllEventsEnable
// ...
return nil
}
// OnStart is called when all Runtime resources are available but looping as not been
// started. Initializations should be done here (GL conf, physics engine ...).
func (app *App) OnStart(runtime tge.Runtime) error {
// Here is the place where your initialize everything, the runtime is UP but the loops
// are not started :
// - OpenGL
// - Physics
// - AI
// - Load previous Save
// - State Machine setup
// ...
return nil
}
// OnResume is called just after OnStart and also when the Runtime is awaken after a pause.
func (app *App) OnResume() {
// This method is called to notify that loops are started, don't place heavey treatments here
// Most of the time, this method is just used to hide/remove a pause screen
}
// OnRender is called each time the graphical context is redrawn. This method should only implements
// graphical calls and not logical ones. The syncChan is used to wait for Tick() loop draw commands
func (app *App) OnRender(elaspedTime time.Duration, syncChan <-chan interface{}) {
// Always listen at least for one object from syncChan to synchronize it with Tick(), in other case the Tick() loop
// will be blocked
<-syncChan
// This loop is dedicated to graphical/GPU treatments:
// - OpenGl Calls
// - Vulkan Calls (one day ;)
//
// Data becomes available from syncChan pipe and sent by the Tick loop, as mentioned below, it's possible to
// reused syncChan several times in a single Render/Tick call for progressive rendering.
//
// As syncChan is a generic interface channel, it's also possible to select treatment to apply:
// data := <-syncChan
// switch data.(type) {
// ...
// }
}
// OnTick handles logical operations like physics, AI or any background task not relatd to graphics.
// The syncChan is used to notify Render() loop with draw commands.
func (app *App) OnTick(elaspedTime time.Duration, syncChan chan<- interface{}) {
// This loop is dedicated to logical/CPU treatments:
// - physics
// - AI
// - State Machine
// - File access ...
//
// Each time Tick loop needs to send data to Render loop, use the syncChan.
//
// In can be done once per call or several times if you want a progressive rendering
//
// As data can be shared between Tick and Render loops, a good practice is too handle heavy treatments
// in Tick dedicated data, then copy data to Render dedicated data and send it through the syncChan.
//
// A good candidate for copy if the reflect.Copy() function:
// reflect.Copy(reflect.ValueOf(renderData), reflect.ValueOf(tickData))
//
// If your data is based on something else than slices but its size justifies low level memory copy, you can
// also put ticker data in single element slice and use reflect.Copy().
//
// Tick loop is running in a dedicated Go routine, it's also possible to start subroutines in this loop to
// benefit from availble cores and increase treatment speed using map/reduce oriented algorithms.
//
// Always send at least one object to syncChan to synchronize it with Render(), in other case the Tick() loop
// will be a simple infinite loop and your App will destroy your Desktop/Mobile/Browser
syncChan <- true
}
// OnPause is called when the Runtime lose focus (alt-tab, home button, tab change ...) This is a good entry point to
// set and display a pause screen
func (app *App) OnPause() {
// Most of the time, just set a flag indicating the paused state of your App
}
// OnStop is called when the Runtime is ending, context saving should be done here. On current Android version this
// handler is also called when the application is paused (and restart after).
func (app *App) OnStop() {
// This is where you backup everyting if needed (state machine, save ...) The runtime tries to call and execute
// this method before leaving to allow proper exit but nothing is guaranteed on some targets (WEB)
}
// OnDispose is called when all exit treatments are done for cleaning task (memory, tmp files ...)
func (app *App) OnDispose() {
// Optional but always good practice to clean up everything before leaving :)
}
// Main entry point, simply instanciates App and runs it through Runtime
func main() {
// The line below should be the only one, code here is not portable!
tge.Run(&App{})
}
Plugins
To create new TGE plugins for sharing or to defines dedicated libraries across your applications, use the code below:
package myplugin
import (
// Always import TGE for initalization purpose
tge "github.com/thommil/tge"
)
// Plugin implementation, no need to expose
type plugin struct {
}
// Go init function, register your plugin on TGE runtime HERE
func init() {
tge.Register(plugin{})
}
// Init code of your plugin, called before runtime loops
func (p *plugin) Init(runtime tge.Runtime) error {
return nil
}
// GetName is used to identify the plugin in TGE registry
func (p *plugin) GetName() string {
return "myplugin"
}
// Dispose allows to clean up plugin resources
func (p *plugin) Dispose() {
}
Targeting platform and debug mode
It's possible to write code for a specific platform the same way TGE does.
For desktop, add the following Go build directives:
// +build darwin freebsd linux windows
// +build !android
// +build !ios
// +build !js
for mobile (targeting only android or ios is also possible):
// +build android ios
and for browser:
// +build js
At last, it's also possible to create a dedicated file for debugging purpose by adding:
// +build debug
The file will be used if the -dev flag is set in tge-cli command line for build.
Documentation
¶
Overview ¶
Package tge core contains interfaces and core implementation for supported targets:
- desktop : MacOS, Linux, Windows
- android : Android 5+
- ios : IOS 8+ (Work in progress)
- browser : Chrome, Firefox, Safari (limited support)
TGE Core should not be used directly, it only defines interfaces and is used by TGE Command Line Tool :
see https://github.com/thommil/tge-cli
App ¶
An App is the main entry point of TGE, the main() function should normally just starts the Runtime, any other code not handled by the Runtime is potenitally not portable:
import "github.com/thommil/tge"
func main() {
tge.Run(&MyApp{})
}
The App interface is described here and the implementation details in the auto generated app.go using tge-cli.
Runtime ¶
The Runtime instance is initialized through the Run(*App) function of main package. At startup, the Runtime looks for registered plugins and initializes them. Then the App instance is initialized and started.
The Runtime instance also exposes API for loading assets and subscribing to events in a generic way.
Runtime exposes none portable objects like Host (backend) and Renderer (graphical context), they can be used to implement custom behaviour depending on target in Apps or Plugins, the implementations are as follows:
Host: - desktop : *sdl.Window - SDL2 from https://github.com/veandco/go-sdl2 - android/ios : mobile.App - Custom gomobile from https://github.com/thommil/tge-mobile - browser : *js.Value - Gobal element through WebAssembly from Go 1.12 Renderer: - desktop : *sdl.GLContext - SDL2 from https://github.com/veandco/go-sdl2 - android/ios : gl.Context - Custom gomobile from https://github.com/thommil/tge-mobile - browser : *js.Value - WebGL/WebGL2 context through WebAssembly from Go 1.12
Rendering ¶
TGE uses Go channel mechanism to handle rendering, two loops are running side by side:
- Ticker loop with Tick() : handle CPU treatments (physics, AI, logical) and trigger rendering
- Render loop with Render() : handle GPU treatments (draw calls)
Both loops are synchronized using a dedicated channel passed in parameter of each method. As this method allows to make CPU/GPU treatments asynchronous, shared objects between contexts must correctly handled to avoid conflicts. The sync channel is typed as interface{}, it can also be used to pass content and select specific treatments based on underlying interface type. See examples for more details.
A good candidate for copy if the reflect.Copy() function:
reflect.Copy(reflect.ValueOf(renderData), reflect.ValueOf(tickData))
If your data is based on something else than slices but its size justifies low level memory copy, you can also put ticker data in a single element slice and use reflect.Copy() on it.
Events ¶
Minimal set of events is handled by Runtime at the most possible portable way. Events are then propagated through publish/subscribe:
Subscribe(channel string, listener Listener) Unsubscribe(channel string, listener Listener) Publish(event Event)
Events are in their raw form (ie modifiers or gestures are not handled). It's up to the application to implement specific needs. The aim of this approach is to keep the runtime generic and fast by limiting treatments.
A dedicated plugin to generate advanced events will be available soon.
Plugins ¶
As TGE core is intended to be as light as possible, all heavy treatments are deported to plugins. The goal is to offer a portable API from Plugins by relying on Runtime.
Plugins are automatically registered at Go init() step, to use it, just import them as standard Go packages, ex:
import "github.com/thommil/tge-gl"
func (app *App) OnStart(runtime tge.Runtime) error{
gl.ClearColor(0, 0, 0, 1)
}
It's also possible to create custom plugins by implementing Plugin interface and registering it in the Go init() function :
package myplugin
import (
tge "github.com/thommil/tge"
)
type plugin struct {
Name string
}
func init() {
tge.Register(plugin{"myplugin"})
}
func (p *plugin) Init(runtime tge.Runtime) error {
// Init code HERE if needed
return nil
}
func (p *plugin) GetName() string {
return p.Name
}
func (p *plugin) Dispose() {
// Dispose code HERE if needed
}
Index ¶
Constants ¶
const ( // AllEventsDisable disables all input events on App AllEventsDisable = 0x00 // MouseButtonEventEnabled enabled mouse buttons events receiver on App MouseButtonEventEnabled = 0x01 // MouseMotionEventEnabled enabled mouse motion events receiver on App MouseMotionEventEnabled = 0x02 // ScrollEventEnabled enabled scroll event receiver on App ScrollEventEnabled = 0x04 // KeyEventEnabled enabled key event receiver on App KeyEventEnabled = 0x08 // AllEventsEnabled enables all input events on App AllEventsEnabled = 0xFFFF )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type App ¶
type App interface {
// OnCreate is called at App instanciation, the Runtime resources are not
// yet available. Settings and treatments not related to Runtime should be done here.
OnCreate(settings *Settings) error
// OnStart is called when all Runtime resources are available but looping as not been
// started. Initializations should be done here (GL conf, physics engine ...).
OnStart(runtime Runtime) error
// OnResume is called just after OnStart and also when the Runtime is awaken after a pause.
OnResume()
// OnRender is called each time the graphical context is redrawn. This method should only implements
// graphical calls and not logical ones. The syncChan is used to wait for Tick() loop draw commands
OnRender(elaspedTime time.Duration, syncChan <-chan interface{})
// OnTick handles logical operations like physics, AI or any background task not relatd to graphics.
// The syncChan is used to notify Render() loop with draw commands.
OnTick(elaspedTime time.Duration, syncChan chan<- interface{})
// OnPause is called when the Runtime lose focus (alt-tab, home button, tab change ...) This is a good entry point to
// set and display a pause screen
OnPause()
// OnStop is called when the Runtime is ending, context saving should be done here. On current Android version this
// handler is also called when the application is paused (and restart after).
OnStop()
// OnDispose is called when all exit treatments are done for cleaning task (memory, tmp files ...)
OnDispose()
}
App is the main entry point of a TGE Application. Created using TGE Command Line Tools.
See generated app.go by tge-cli for more details and explanations.
type Button ¶
type Button byte
Button indicates the type of button or touch used in event
const ( // ButtonNone Button for not available or not applicable ButtonNone Button = 0x00 // ButtonLeft Button for left button ButtonLeft Button = 0x01 // ButtonRight Button for right button ButtonRight Button = 0x02 // ButtonMiddle Button for middle button ButtonMiddle Button = 0x04 // TouchFirst Button for first finger touch TouchFirst Button = 0x10 // TouchSecond Button for second finger touch TouchSecond Button = 0x20 // TouchThird Button for third finger touch TouchThird Button = 0x40 // ButtonLeftOrTouchFirst helper to test left button or first touch ButtonLeftOrTouchFirst Button = 0x11 )
Buttons values
type Event ¶
type Event interface {
// Type defines a unique keywork/channel for event
Channel() string
}
Event interface defines an event base by its channel
type EventMask ¶
type EventMask int
EventMask defines mask event for enable/disable events receivers at runtime level
type KeyCode ¶
type KeyCode int
KeyCode is used to map raw key codes values
const ( KeyCodeUnknown KeyCode = 0 // Printable KeyCodeA KeyCode = 1 KeyCodeB KeyCode = 2 KeyCodeC KeyCode = 3 KeyCodeD KeyCode = 4 KeyCodeE KeyCode = 5 KeyCodeF KeyCode = 6 KeyCodeG KeyCode = 7 KeyCodeH KeyCode = 8 KeyCodeI KeyCode = 9 KeyCodeJ KeyCode = 10 KeyCodeK KeyCode = 11 KeyCodeL KeyCode = 12 KeyCodeM KeyCode = 13 KeyCodeN KeyCode = 14 KeyCodeO KeyCode = 15 KeyCodeP KeyCode = 16 KeyCodeQ KeyCode = 17 KeyCodeR KeyCode = 18 KeyCodeS KeyCode = 19 KeyCodeT KeyCode = 20 KeyCodeU KeyCode = 21 KeyCodeV KeyCode = 22 KeyCodeW KeyCode = 23 KeyCodeX KeyCode = 24 KeyCodeY KeyCode = 25 KeyCodeZ KeyCode = 26 KeyCode1 KeyCode = 27 KeyCode2 KeyCode = 28 KeyCode3 KeyCode = 29 KeyCode4 KeyCode = 30 KeyCode5 KeyCode = 31 KeyCode6 KeyCode = 32 KeyCode7 KeyCode = 33 KeyCode8 KeyCode = 34 KeyCode9 KeyCode = 35 KeyCode0 KeyCode = 36 KeyCodeReturnEnter KeyCode = 37 KeyCodeTab KeyCode = 38 KeyCodeSpacebar KeyCode = 39 KeyCodeHyphenMinus KeyCode = 40 // - KeyCodeEqualSign KeyCode = 41 // = KeyCodeLeftSquareBracket KeyCode = 42 // [ KeyCodeRightSquareBracket KeyCode = 43 // ] KeyCodeBackslash KeyCode = 44 // \ KeyCodeSemicolon KeyCode = 45 // ; KeyCodeApostrophe KeyCode = 46 // ' KeyCodeGraveAccent KeyCode = 47 // ` KeyCodeComma KeyCode = 48 // , KeyCodeFullStop KeyCode = 49 // . KeyCodeSlash KeyCode = 50 // / KeyCodeKeypadSlash KeyCode = 51 // / KeyCodeKeypadAsterisk KeyCode = 52 // * KeyCodeKeypadHyphenMinus KeyCode = 53 // - KeyCodeKeypadPlusSign KeyCode = 54 // + KeyCodeKeypadEnter KeyCode = 55 KeyCodeKeypad1 KeyCode = 56 KeyCodeKeypad2 KeyCode = 57 KeyCodeKeypad3 KeyCode = 58 KeyCodeKeypad4 KeyCode = 59 KeyCodeKeypad5 KeyCode = 60 KeyCodeKeypad6 KeyCode = 61 KeyCodeKeypad7 KeyCode = 62 KeyCodeKeypad8 KeyCode = 63 KeyCodeKeypad9 KeyCode = 64 KeyCodeKeypad0 KeyCode = 65 KeyCodeKeypadFullStop KeyCode = 66 // . KeyCodeKeypadEqualSign KeyCode = 67 // = KeyCodeAt KeyCode = 68 // @ KeyCodeGreaterThan KeyCode = 69 // > KeyCodeLesserThan KeyCode = 70 // < KeyCodeDollar KeyCode = 71 // $ KeyCodeColon KeyCode = 72 // : KeyCodeLeftParenthesis KeyCode = 73 // ( KeyCodeLRightParenthesis KeyCode = 74 // ) KeyCodeAmpersand KeyCode = 75 // & KeyCodeHash KeyCode = 76 // # KeyDoubleQuote KeyCode = 77 // " KeyQuote KeyCode = 78 // ' KeyParapgrah KeyCode = 79 // § KeyExclamationMark KeyCode = 80 // ! KeyUnderscore KeyCode = 81 // _ KeyQuestionMark KeyCode = 82 // ? KeyPercent KeyCode = 83 // % KeyDegree KeyCode = 84 // ° KeyCodeEscape KeyCode = 101 KeyCodeCapsLock KeyCode = 102 KeyCodeDeleteBackspace KeyCode = 103 KeyCodePause KeyCode = 104 KeyCodeInsert KeyCode = 105 KeyCodeHome KeyCode = 106 KeyCodePageUp KeyCode = 107 KeyCodeDeleteForward KeyCode = 108 KeyCodeEnd KeyCode = 109 KeyCodePageDown KeyCode = 110 KeyCodeRightArrow KeyCode = 111 KeyCodeLeftArrow KeyCode = 112 KeyCodeDownArrow KeyCode = 113 KeyCodeUpArrow KeyCode = 114 KeyCodeKeypadNumLock KeyCode = 115 KeyCodeHelp KeyCode = 116 KeyCodeMute KeyCode = 120 KeyCodeVolumeUp KeyCode = 121 KeyCodeVolumeDown KeyCode = 122 KeyCodeF1 KeyCode = 201 KeyCodeF2 KeyCode = 202 KeyCodeF3 KeyCode = 203 KeyCodeF4 KeyCode = 204 KeyCodeF5 KeyCode = 205 KeyCodeF6 KeyCode = 206 KeyCodeF7 KeyCode = 207 KeyCodeF8 KeyCode = 208 KeyCodeF9 KeyCode = 209 KeyCodeF10 KeyCode = 210 KeyCodeF11 KeyCode = 211 KeyCodeF12 KeyCode = 212 KeyCodeLeftControl KeyCode = 301 KeyCodeLeftShift KeyCode = 302 KeyCodeLeftAlt KeyCode = 303 KeyCodeLeftGUI KeyCode = 304 KeyCodeRightControl KeyCode = 305 KeyCodeRightShift KeyCode = 306 KeyCodeRightAlt KeyCode = 307 KeyCodeRightGUI KeyCode = 308 KeyCodeCompose KeyCode = 0x10000 )
Keycode constants
func (KeyCode) IsFunction ¶
IsFunction indicates a function KeyCode
func (KeyCode) IsModifier ¶
IsModifier indicates a modifier KeyCode
func (KeyCode) IsPrintable ¶
IsPrintable indicates a printable KeyCode
type KeyEvent ¶
KeyEvent defines a down/up key event, the Key attribute is portable across targets, the Value is the string representation of the key
type Listener ¶
Listener is the callback definition for publish/subscribe, the return value indicates if the event has been consumed (true) and propagation stopped, in other case the next registered Listener is called
type MouseEvent ¶
MouseEvent is triggered on mouse/touch down/up event and mouse motion event too
type Plugin ¶
type Plugin interface {
// Init is called before Runtime looping
Init(runtime Runtime) error
// GetName allows Runtime to identify plugin by its name
GetName() string
// Dispose is called at end of Runtime before exiting
Dispose()
}
Plugin interface defines the API used by the Runtime to handle plugins
type ResizeEvent ¶
type ResizeEvent struct {
Width, Height int32
}
ResizeEvent is triggered when TGE painting area is resized
func (ResizeEvent) Channel ¶
func (e ResizeEvent) Channel() string
Channel of ResizeEvent = "resize"
type Runtime ¶
type Runtime interface {
// GetAsset retrieves assets in []byte form, assets are always stored in
// package asset folder independently of the target
GetAsset(path string) ([]byte, error)
// GetHost is for low level and target specific implementation and allows to
// retrieve the underlying backend of the Runtime (see package description)
GetHost() interface{}
// GetRenderer is for low level and target specific implementation and allows to
// retrieve the underlying graphical context of the Runtime (see package description)
GetRenderer() interface{}
// GetSettings returns the current Runtime settings
GetSettings() Settings
// Subscribe register a new Listener to specified channel
Subscribe(channel string, listener Listener)
// Unsubscribe deregister a new Listener from specified channel
Unsubscribe(channel string, listener Listener)
// Publish send an Event on channel defined in the Event.Channel()
Publish(event Event)
// Stop allows App to end the Runtime directly
Stop()
}
Runtime defines the commmon API across runtimes implementations
type ScrollEvent ¶
type ScrollEvent struct {
X, Y int32
}
ScrollEvent is called only on desktop/browser, X/Y values are only [-1, 0, 1] to normalize scrolling across targets
func (ScrollEvent) Channel ¶
func (e ScrollEvent) Channel() string
Channel of ScrollEvent = "scroll"
type Settings ¶
type Settings struct {
// Name of the App
Name string `json:"name" yaml:"name"`
// Fullscreen indicates if the app must be run in fullscreen mode
Fullscreen bool `json:"fullscreen" yaml:"fullscreen"`
// Width of the window if run windowed only
Width int `json:"width" yaml:"width"`
// Height of the window if run windowed only
Height int `json:"height" yaml:"height"`
// EventMask allows to enabled/disable events receiver on Runtime
EventMask EventMask `json:"event_mask" yaml:"event_mask"`
}
Settings definition of TGE application
type Type ¶
type Type byte
Type is a component of events to indicate a generic way of defining an event action.
Source Files
Directories