# README
Engo
A cross-platform game engine written in Go following an interpretation of the Entity Component System paradigm. Engo is currently compilable for Mac OSX, Linux and Windows. With the release of Go 1.4, supporting Android and the inception of iOS compatibility, mobile has been be added as a release target. Web support (wasm) is also available.
v1.0 is now available! To celebrate, there will be a game jam coming soon to celebrate the release, start actually building things and hopefully find any issues. Updates for this will come soon.
Getting in touch / Contributing
We have a gitter chat for people to join who want to further discuss engo. We are happy to discuss bugs, feature requests and would love to hear about the projects you are building!
Getting Started
Theory: common vs engo
There are currently two major important packages within this repository: github.com/EngoEngine/engo and github.com/EngoEngine/engo/common.
The top level engo package contains the functionality of creating windows, starting the game, creating an OpenGL
context and handling input. It is designed to be used with Systems designed as per github.com/EngoEngine/ecs specifications.
The common package contains our ECS implementations of common game development Systems like a RenderSystem or
CameraSystem.
Practice: Getting it to Run
- First, you have to install some dependencies:
- If you're running on Debian/Ubuntu:
sudo apt-get install libasound2-dev libglu1-mesa-dev freeglut3-dev mesa-common-dev xorg-dev libgl1-mesa-dev git-all - If you're running on Windows you'll need a gcc compiler that the go tool can use and have
gcc.exein your PATH environmental variable. We recommend Mingw since it has been tested. You'll also need git installed, we recommend getting it from The official Git site - If you're on OSX, you will also need Git. You can find instructions here. You can also use homebrew to install git as well. Open an issue if you have any issues
- Then, you can go get it:
go get -u github.com/EngoEngine/engo - You may also want to get the dependencies of platform specific builds, so that build tools like godef can use them:
go get -u -tags js ./...go get -u -tags android ./... - Now, you have two choices:
- Visit our website, which hosts a full-blown tutorial series on how to create your own game, and on top of that, has some conceptual explanations;
- Check out some demos in our demos folder.
- Finally, if you run into problems, if you've encountered a bug, or want to request a feature, feel free to shoot us a DM or create an issue.
Breaking Changes Since v1.0
Engo is always undergoing a lot of optimizations and constantly gets new features. However, this sometimes means things break. In order to make transitioning easier for you, we have a list of those changes, with the most recent being at the top. If you run into any problems, please contact us at gitter.
- TMXObject Width and Height is in pixels, and can be fractional. This has changed from an int to a float64.
- TMXTileset now uses a Spritesheet instead of a Texture. This helps keep track of the guid better and allows the gid to not start at zero and have skips in it, as well as for borders and spacing in the tile sheet.
- TMX Level's objects have all been rolled into Object rather than have separate things like "PolyLineObject". This is to be consistent with the TMX format.
- The Shader interface now has a
SetCamera(*CameraSystem)method. This method allows shaders to automatically update the camera system as it changes, such as between scenes or when the camera system is added. - The domain engo.io has expired. Now use
github.com/EngoEngine/engoas the import path, and the site can be located at engoengine.github.io
Roadmap to v1.1
A list of issues for v1.1 can be found here. There's always room for improvement! Feel free to submit proposals, open issues, and let us know how we can improve!
History
Engo, originally known as Engi was written by ajhager as a general purpose Go game engine. With a desire to build it into an "ECS" game engine, it was forked to github.com/paked/engi. After passing through several iterations, it was decided that the project would be rebranded and rereleased as Engo on its own GitHub organization.
Credits
Thank you to everyone who has worked on, or with Engo. None of this would be possible without you, and your help has been truly amazing.
- ajhager: Building the original
engi, which engo was based off of - paked: Adding ECS element, project maintenance and management
- Newbrict: Font rendering, TMX support
- EtienneBruines: Rewriting the OpenGL code, maintenance and helping redesign the API
- otraore: Adding in GopherJS support, maintenance
- Everyone else who has submitted PRs or issues over the years, to any iteration of the project
These are 3rd party projects that have made engo possible.
- The original engi game engine which engo was based off of (BSD license)
- Oto, a low-level cross-platform library to play sound. The AudioSystem uses this and is based on the audio package used in Ebiten.
# Functions
CanvasHeight gets the height of the current OpenGL Framebuffer.
CanvasScale gets the ratio of the canvas to the window sizes.
CanvasWidth gets the width of the current OpenGL Framebuffer.
CreateWindow sets up the GLFW window and prepares the OpenGL surface for rendering.
CrossProduct returns the 2 dimensional cross product of this and that, which represents the magnitude of the three dimensional cross product.
CurrentScene returns the SceneWorld that is currently active.
CursorPos returns the current cursor position.
DestroyWindow handles the termination of windows.
DotProduct returns the dot product between this and that.
Exit is the safest way to close your game, as `engo` will correctly attempt to close all windows, handlers and contexts.
FloatEqual is a safe utility function to compare floats.
FloatEqualThreshold is a utility function to compare floats.
GameHeight returns the current game height.
GameWidth returns the current game width.
GetApplicationVersion returns the major, minor, and revision of the game.
GetGlobalScale returns the GlobalScale factor set in the RunOptions or via SetGlobalScale().
GetKeyName returns the string returned from the given Key.
GetTitle returns the title of the game.
Headless indicates whether or not OpenGL-calls should be made.
IdentityMatrix returns a new identity matrix.
IsAndroidChrome tells if the browser is Chrome for android.
LineIntersection returns the point where the line segments one and two intersect and true if there is intersection, nil and false when line segments one and two do not intersect.
LineTrace runs a series of line traces from tracer to each boundary line and returns the nearest trace values.
LineTraceFraction returns the trace fraction of tracer through boundary 1 means no intersection 0 means tracer's origin lies on the boundary line.
MultiplyMatrixVector multiplies the matrix m with the float32 vector v and returns the result.
NewAxisMouse creates a new Mouse Axis in either direction AxisMouseVert or AxisMouseHori.
NewClock creates a new timer which allows you to measure ticks per seconds.
NewGamepadManager creates a new GamepadManager.
NewInputManager holds onto anything input related for engo.
NewKeyManager creates a new KeyManager.
NewQuadtree creates a new quadtree for the given bounds.
RegisterScene registers the `Scene`, so it can later be used by `SetSceneByName`.
Run is called to create a window, initialize everything, and start the main loop.
RunIteration runs one iteration per frame.
RunPreparation is called automatically when calling Open.
ScaleOnResize indicates whether or not the screen should resize (i.e.
SetCursor sets the pointer of the mouse to the defined standard cursor.
SetCursorVisibility sets the visibility of the cursor.If true the cursor is visible, if false the cursor is not.
SetFPSLimit can be used to change the value in the given `RunOpts` after already having called `engo.Run`.
SetGlobalScale sets the GlobalScale to the given dimensions.
SetOverrideCloseAction can be used to change the value in the given `RunOpts` after already having called `engo.Run`.
SetScaleOnResize can be used to change the value in the given `RunOpts` after already having called `engo.Run`.
SetScene sets the currentScene to the given Scene, and optionally forcing to create a new ecs.World that goes with it.
SetSceneByName does a lookup for the `Scene` where its `Type()` equals `name`, and then sets it as current `Scene`.
SetTitle sets the title of the window.
SetVSync sets whether or not to use VSync.
WindowHeight gets the current window height.
WindowSize gets the current window size.
WindowWidth gets the current window width.
# Constants
AxisMax is the maximum value a joystick or keypress axis will reach.
AxisMin is the minimum value a joystick or keypress axis will reach.
AxisMouseHori is vertical mouse axis.
AxisMouseVert is vertical mouse axis.
AxisNeutral is the value an axis returns if there has been to state change.
BackEndGLFW uses glfw.
BackEndHeadless does not use a window manager for the backend.
BackEndMobile uses gomobile.
BackEndSDL uses sdl2.
BackEndVulkan uses glfw 3.3 from vulkan-go and vulkan as a render surface.
BackEndWeb uses gopherjs.
CursorArrow represents an arrow cursor.
CursorCrosshair represents a crosshair cursor.
CursorHand represents a hand cursor.
CursorHResize represents a HResize cursor.
CursorIBeam represents an IBeam cursor.
CursorNone can be used to reset the cursor.
CursorVResize represents a VResize cursor.
DefaultHorizontalAxis is the name of the default horizontal axis, as used internally in `engo` when `StandardInputs` is defined.
DefaultMouseXAxis is the name of the default horizontal mouse axis.
DefaultMouseYAxis is the name of the default vertical mouse axis.
DefaultVerticalAxis is the name of the default vertical axis, as used internally in `engo` when `StandardInputs` is defined.
DegToRad is multiplied with a degree value to get the equivalent value in radians.
Epsilon is some tiny value that determines how precisely equal we want our floats to be.
KeyA represents the 'A' keyboard key.
KeyApostrophe represents the `'` keyboard key.
KeyArrowDown represents the down arrow keyboard key.
KeyArrowLeft represents the arrow left keyboard key.
KeyArrowRight represents the arrow right keyboard key.
KeyArrowUp represents the up arrow keyboard key.
KeyB represents the 'B' keyboard key.
KeyBackslash represents the '\' keyboard key.
KeyBackspace represents the backspace keyboard key.
KeyC represents the 'C' keyboard key.
KeyCapsLock represents the caps lock keyboard key.
KeyComma represents the ',' keyboard key.
KeyD represents the 'D' keyboard key '.
KeyDash represents the '-' keyboard key.
KeyDelete represents the delete keyboard key.
KeyE represents the 'E' keyboard key.
KeyEight represents the '8' keyboard key.
KeyEnd represents the end keyboard key.
KeyEnter represents the enter keyboard key.
KeyEquals reprsents the '=' keyboard key.
KeyEscape represents the escape keyboard key.
KeyF represents the 'F' keyboard key.
KeyF1 represents the 'F1' keyboard key.
KeyF10 represents the 'F10' keyboard key.
KeyF11 represents the 'F11' keyboard key.
KeyF12 represents the 'F12' keyboard key.
KeyF2 represents the 'F2' keyboard key.
KeyF3 represents the 'F3' keyboard key.
KeyF4 represents the 'F4' keyboard key.
KeyF5 represents the 'F5' keyboard key.
KeyF6 represents the 'F6' keyboard key.
KeyF7 represents the 'F7' keyboard key.
KeyF8 represents the 'F8' keyboard key.
KeyF9 represents the 'F9' keyboard key.
KeyFive represents the '5' keyboard key.
KeyFour represents the '4' keyboard key.
KeyG represents the 'G' keyboard key.
KeyGrave represents the '`' keyboard key.
KeyH represents the 'H' keyboard key.
KeyHome represents the home keyboard key.
KeyI represents the 'I' keyboard key.
KeyInsert represents the insert keyboard key.
KeyJ represents the 'J' keyboard key.
KeyK represents the 'K' keyboard key.
KeyL represents the 'L' keyboard key.
KeyLeftAlt represents the left alt keyboard key.
KeyLeftBracket represents the '[' keyboard key.
KeyLeftControl represents the left control keyboard key.
KeyLeftShift represents the left shift keyboard key.
KeyLeftSuper represents the left super keyboard key (Windows key on Microsoft Windows, Command key on Apple OSX, and varies on Linux).
KeyM represents the 'M' keyboard key.
KeyN represents the 'N' keyboard key.
KeyNine represents the '9' keyboard key.
KeyNumAdd represents the NumAdd keyboard key on the numpad.
KeyNumDecimal represents the NumDecimal keyboard key on the numpad.
KeyNumDivide represents the NumDivide keyboard key on the numpad.
KeyNumEight represents the NumEight keyboard key on the numpad.
KeyNumEnter represents the NumEnter keyboard key on the numpad.
KeyNumFive represents the NumFive keyboard key on the numpad.
KeyNumFour represents the NumFour keyboard key on the numpad.
KeyNumLock represents the NumLock keyboard key on the numpad.
KeyNumMultiply represents the NumMultiply keyboard key on the numpad.
KeyNumNine represents the NumNine keyboard key on the numpad.
KeyNumOne represents the NumOne keyboard key on the numpad.
KeyNumSeven represents the NumSeven keyboard key on the numpad.
KeyNumSix represents the NumSix keyboard key on the numpad.
KeyNumSubtract represents the NumSubtract keyboard key on the numpad.
KeyNumThree represents the NumThree keyboard key on the numpad.
KeyNumTwo represents the NumTwo keyboard key on the numpad.
KeyNumZero represents the NumZero keyboard key on the numpad.
KeyO represents the 'O' keyboard key.
KeyOne represents the '1' keyboard key.
KeyP represents the 'P' keyboard key.
KeyPageDown represents the page down keyboard key.
KeyPageUp represents the page up keyboard key.
KeyPause represents the pause keyboard key.
KeyPeriod represents the '.' keyboard key.
KeyPrintScreen represents the print screen keyboard key often represented by 'Prt Scrn', 'Prt Scn', or 'Print Screen'.
KeyQ represents the 'Q' keyboard key.
KeyR represents the 'R' keyboard key.
KeyRightAlt represents the left alt keyboard key.
KeyRightBracket represents the ']' keyboard key.
KeyRightControl represents the right control keyboard key.
KeyRightShift represents the right shift keyboard key.
KeyRightSuper represents the right super keyboard key (Windows key on Microsoft Windows, Command key on Apple OSX, and varies on Linux).
KeyS represents the 'S' keyboard key.
KeyScrollLock represents the scroll lock keyboard key.
KeySemicolon represents the ';' keyboard key.
KeySeven represents the '7' keyboard key.
KeySix represents the '6' keyboard key.
KeySlash represents the '/' keyboard key.
KeySpace represents the space keyboard key.
KeyStateDown is a state for when the key is currently being pressed.
KeyStateJustDown is a state for when a key was just pressed.
KeyStateJustUp is a state for when a key was just released.
KeyStateUp is a state for when the key is not currently being pressed.
KeyT represents the 'T' keyboard key.
KeyTab represents the tab keyboard key.
KeyThree represents the '3' keyboard key.
KeyTwo represents the '2' keyboard key.
KeyU represents the 'U' keyboard key.
KeyV represents the 'V' keyboard key.
KeyW represents the 'W' keyboard key.
KeyX represents the 'X' keyboard key.
KeyY represents the 'Y' keyboard key.
KeyZ represents the 'Z' keyboard key.
KeyZero represents the '0' keyboard key.
1 / 2**(127 - 1).
MouseButton4 represents the 4th mouse button.
MouseButton5 represents the 5th mouse button.
MouseButton6 represents the 6th mouse button.
MouseButton7 represents the 7th mouse button.
MouseButton4 represents the last mouse button.
MouseButtonLeft represents the left mouse button.
MouseButtonMiddle represent the middle mosue button.
MouseButtonRight represents the right mouse button.
RadToDeg is multiplied with a radian value to get the equivalant value in degrees.
# Variables
Alt represents the alt modifier It is triggered when the alt key is pressed simultaneously with another key.
Control represents the control modifier It is triggered when the ctrl key is pressed simultaneously with another key.
CurrentBackEnd is the current back end used for window management.
Files manages global resource handling of registered file formats for game assets.
Gl is the current OpenGL context.
Input handles all input: mouse, keyboard and touch.
Mailbox is used by all Systems to communicate.
Move is an action representing mouse movement.
Neutral represents a neutral action.
Press is an action representing a mouse press/click.
Release is an action representing a mouse a release.
ResizeXOffset is how far the screen moves from (0,0) being the top-left corner when the window is resized.
ResizeYOffset is how far the screen moves from (0,0) being the top-left corner when the window is resized.
Shift represents the shift modifier.
Super represents the super modifier (Windows key on Microsoft Windows, Command key on Apple OSX, and varies on Linux) It is triggered when the super key is pressed simultaneously with another key.
Time is the active FPS counter.
Window is the glfw.Window used for engo.
# Structs
AABB describes two points of a rectangle: the upper-left corner and the lower-right corner.
An Axis is an input which is a spectrum of values.
No description provided by the author
An AxisKeyPair is a set of Min/Max values used for detecting whether or not a key has been pressed.
AxisMouse is an axis for a single x or y component of the Mouse.
A Button is an input which can be either JustPressed, JustReleased or Down.
A Clock is a measurement built in `engo` to measure the actual frames per seconds (framerate).
Formats manages resource handling of registered file formats.
Gampad is a configuration of a joystick that is able to be mapped to the SDL_GameControllerDB.
Gamepadbutton is a button on a Gamepad.
GamepadManager manages the gamepads.
No description provided by the author
InputManager contains information about all forms of input.
KeyManager tracks which keys are pressed and released at the current point of time.
KeyState is used for detecting the state of a key press.
Line describes a line segment on a 2 dimensional euclidean space it can also be thought of as a 2 dimensional vector with an offset.
Matrix describes a 3x3 column-major matrix useful for 2D transformations.
MessageManager manages messages and subscribed handlers.
Mouse represents the mouse.
MouseState represents the current state of the Mouse (or latest Touch-events).
Point describes a coordinate in a 2 dimensional euclidean space it can also be thought of as a 2 dimensional vector from the origin.
Quadtree implementation which can store AABBer values.
RunOptions are the options used to Run engo.
TextMessage is a message that is dispatched whenever a character is typed on the keyboard.
Trace describes all the values computed from a line trace.
WindowResizeMessage is a message that's being dispatched whenever the game window is being resized by the gamer.
# Interfaces
AABBer is an interface for everything that provides information about its axis aligned bounding box.
An AxisPair is a set of Min/Max values which could possible be used by an Axis.
A Container is a 2D closed shape which contains a set of points.
Exiter is an optional interface a Scene can implement, indicating it'll have custom behavior whenever the game get closed.
FileLoader implements support for loading and releasing file resources.
FileLoaderRooter must be implemented by file loaders that need to known the root for their own functionning.
Hider is an optional interface a Scene can implement, indicating it'll have custom behavior whenever the Scene get hidden to make room fr other Scenes.
A Message is used to send messages within the MessageManager.
Resource represents a game resource, such as an image or a sound.
Scene represents a screen ingame.
Shower is an optional interface a Scene can implement, indicating it'll have custom behavior whenever the Scene gets shown again after being hidden (due to switching to other Scenes).
Updater is an interface for what handles your game's Update during each frame.
# Type aliases
Action corresponds to a control action such as move, press, release.
AxisMouseDirection is the direction (X or Y) which the mouse is being tracked for.
BackEnd represents the back end used for the window management / GL Surface.
Cursor is a reference to standard cursors, to be used in conjunction with `SetCursor`.
Key correspends to a keyboard key.
A MessageHandler is used to dispatch a message to the subscribed handler.
MessageHandlerId is used to track handlers, each handler will get a unique ID.
Modifier represents a special key pressed along with another key.
MouseButton corresponds to a mouse button.