jerboaburrow / hop

Lightweight, cross-platform, 2D game engine | ECS; Lua Console; Physics; Tile based

Hop

A lightweight 2D game engine, in C++ with embedded Lua

Features

• Free, MIT open sourced
• Use as a standalone (GLFW based) engine or as a drop in component (e.g. with SFML)
• Entity component system (ECS) based
• Rigid and soft body physics (Discrete element method)
• OpenGL rendering (provided by jGL, Vulkan is a WIP)
• Perlin (marching squares) and Tile map, editable tile based worlds
• Lua console, interoperating with the ECS, physics, and rendering systems

Setup

• clone, and init the submodules (you can use submodules.sh)
• the build.sh can be used to build

OSS Dependencies and Licenses

• Freetype is licensed under the The FreeType Project LICENSE
• GLEW is licensed under aModified BSD License, the Mesa 3-D License (MIT) and the Khronos License (MIT).
• GLFW is licensed under the zlib/libpng
• GLM is licensed under the MIT License (but also, no bunnies have been made unhappy)
• Lua is licensed under the MIT license
• Miniaudio is licensed under the MIT-0 license
• stduuid is licensed under the MIT license
• vorbis and ogg is licensed under a BSD license
• zlib is licensed under the zlib license

We thank: David Turner, Robert Wilhelm, and Werner Lemberg (Freetype), Milan Ikits <milan ikits[]ieee org>, Marcelo E. Magallon <mmagallo[]debian org>, and Lev Povalahev Brian Paul, The Khronos Group Inc (GLEW), Marcus Geelnard and Camilla Löwy (GLFW), G-Truc Creation (GLM), Lua.org, PUC-Rio (Lua), David Reid (Miniaudio), Marius Bancila https://github.com/mariusbancila/stduuid#MIT-1-ov-file (stduuid), Xiph.org Foundation (vorbis, ogg), and Jean-loup Gailly and Mark Adler (zlib).

hop's Issues

Automate dummy app run (Android emulator)

• example app build #50
• emulator in yaml
• action with screenshot of emulator

Isometric perspective

• support isometric perspective
• mouse transforms
• textures with "height"
• draw order

Create Android example and benchmark using NDK wrapper

• hop as a lib #45
• refactor GLSkeleton app with Balance's and SPP's compose updates
• refactor GLSkeleton app with Balance's OnlineServices API
• test play games services
• build Hop for android using NDK
• map in example
• move around map
• add particles
• benchmark on Nexus 5
• add hop android build to yml
• add android example to yml (emulator)

GLFW, SDL2, SFML examples

• GLFW
• SDL2
• SFML

Borked rotational dynamics

Will a friction force solve it?

Map and world

• Procedural map generation
• Tile based, top down
• Lighting and physics informed by map

Geometry/Maths Library

• refactor Vertex
• collate/refactor geometry./math methods from all code

Threaded physics bug

strange lagging behaviour

Borked rectangles

• unstable oscillations near settling
• collision detection issue?
• does abate at dt 1/9000, 10 subsamples...

dt

https://gafferongames.com/post/fix_your_timestep/

Texture Atlasing

const char * texturedQuadVertexShader = "#version 330 core\n"
    "layout(location=0) in vec4 a_position;\n"
    "layout(location=1) in vec4 a_offset;\n"
    "layout(location=2) in vec4 a_colour;\n"
    "uniform mat4 proj;\n"
    "out vec2 texCoord;\n"
    "void main(){\n"
        "gl_Position = proj*vec4(a_offset.z*a_position.xy+a_offset.xy,0.0,1.0);\n"
        "texCoord = a_position.zw;\n"
    "}";

const char * texturedQuadFragmentShader = "#version 330 core\n"
    "in vec2 texCoord;\n"
    "uniform sampler2D tex; out vec4 colour;\n"
    "void main(){"
        "colour=texture(tex,texCoord);"
    "\n}";

Camera

• Support zooming
• Support different resolutions and aspect ratios

Automate Dummy app run (Desktop)

Use Xvbf to virtually run test games and maybe even save screenshots (see if it crashes, human interpret screenshot)

https://unix.stackexchange.com/questions/365268/how-do-i-take-a-screen-shot-of-my-xvfb-buffer

https://stackoverflow.com/questions/63125480/running-a-gui-application-on-a-ci-service-without-x11

• Linux graphics test (d1e0517)
• Mac
• windows

Unstable physics when object move from inside a cell to outside

If an object is in a cell (e.g. 15) not collision forces are applied

But when it crosses (centre point) outside a large force is applied

• grace period to not apply forces?

Zlib not linking statically

.so is built and .a ...

C++17 and Style

Fully adopt the following

• std::filesystem
• parallel STL (find, sort etc.)
• range-for

Style

• Brace initialisation (e.g. int a {7}
• no forward declaration of types ala Fortran

rectangle implied c.of.r high

• suspended rectangles colliding

IOS Support

Higher order integration; subsampling

Explore possibility for higher order integration and timestep subsampling

• Yoshida integrator (4th order)
• Yoshida with linear force model (rather than recomputing forces)
• Yoshida with non-linear force model (rather than recomputing forces)
• Sub-sample time step option

Template core types

E.g. template out float or double precision for all physics methods

Windows support

Build types working need to test threading also works

• build auto test
• add windows artifact action step
• human test threads work

Machine Learning

Use flashlight for ML?

Perhaps develop an interface with the Lua scripting?

Supported vertices for rectangle?

• rectangle vertices supported by surface (have collided recently) apply no gravity
• help with rotation (symmetry breaking)?

Refactor main.cpp into a demo application (desktop)

• Move main.cpp out of hop
• Build Hop as a static lib
• create demo/
• create a demo app for testing in demo/

Refactor to use brace style (and spacing); define style guide

• brace style refactored
• style guide doc
• deal with warnings

E.g from this

    for (int i = 0; i < DYNAMICS_REGION_BUFFER_SIZE; i++){
        for (int j = 0; j < DYNAMICS_REGION_BUFFER_SIZE; j++){
            renderRegionBuffer[i*DYNAMICS_REGION_BUFFER_SIZE+j] = map->getAtCoordinate(i,j);
        }
    }

to

    for (int i = 0; i < DYNAMICS_REGION_BUFFER_SIZE; i++)
    {

        for (int j = 0; j < DYNAMICS_REGION_BUFFER_SIZE; j++)
        {

            renderRegionBuffer[i*DYNAMICS_REGION_BUFFER_SIZE+j] = map->getAtCoordinate(i,j);
        
        }
        
    }

Rectangle Primitive Oscillations/ Colliosion correctness

• [case] Rectangle primitives oscillate when settling, due to incorrect torque for collision handling

• need to correctly implement collision resolution

• adding a damping (omega -= phi) caused NaN's for circles

Refactor to use namespaces

E.g Hop::Text, Hop::World, Hop::Util, etc. or something similar

Lua

• embed Lua into engine
• support object creation via Lua scripts (to begin with)

Composite shapes (circles primitive only)

• fix collision detection
• fix rotational dynamics

Physics

cell list based collisions

256x256 cells worked at 60fps for 100k particles on CellLists repo!

android might be an issue, but that could be just Kotlin (balance repo)

e: roughly 100 particles per object with (100k)

• object-object collisions
• object-world collisions (marching squares)
• object-world collisions (tile based)

Collision Primitives

Support both lines and circles as collision Primitives within collision mesh

• refactor collision mesh/ vertex to use collision primitive

• Circle primitive

• Ellipse primitive

• square primitive

Using Rectangle primitive

• deprecate LineSegment
• Rectangle - world vertices update
• Use p-axis to cull, Then test each vertex and apply
• Apply forces at point (for rotation)
• Rect-Rect force
• Rect-Circle force
• add debug shaders for CollisionMesh
• spawn rectangles for bounds col with rect object
• spawn rectangles for world col with rect object
• Rect-world (Rect) force
• test example

Lua lbaselib.c coloured print adds extra "read" to string

• [case] The colour code prints, print("text") as "[LUA] readtext", where [LUA] was correctly in blue, but the extra "read" string was added

// #if !defined(ANDROID) && !defined(WINDOWS)
// const char * LUA_PRINT_ENTRY = "\033[1;34m[LUA] \033[0m";
// const size_t LUA_ENTRY_LENGTH = 23;
// #else
// it is more complicated than this, LUA interprets some of
// the escapes differently
const char * LUA_PRINT_ENTRY = "[LUA] ";
const size_t LUA_ENTRY_LENGTH = 6;
// #endif

False sharing

thread jobs in system allocate as object 0 to thread 0, 1 to 1, i to i % threads

this leads to threaded data locality and false sharing??

• implement new job loading scheme

Thread Utilisation

Currently with 8 threads util is

main 99%
1-7 ~50%

More threading in collision system maybe?

OSX support

No support, need to work out how to test on a mac

Behaviour

Embed Lua to script 'AI' behaviour, items, etc

MarchingWorld and TileWorld

• Marching squares based worlds cannot form all tile based worlds

• Split world into MarchingXWorld and TileWorld

• TileWorld will need more careful collision treatment

• refactor to World[MarchingWorld,TileWorld] World [MarchingWorld[PerlinWorld,FixedWorld],TileWorld] abstraction (FixedWorld here is a TileWorld

• specify map file type

• refactor TileWorld to use the MapSource abstraction

• Support different sources for the MarchingWorld's scalar field as FieldSource[FixedSource,PerlinSource]

• Support collisions in TileWorld (see image). Will require 3x3 tile checking for additional walls

• Support PerlinSource with a FixedSource (overrider?), (i.e. save user interactions with world ala minceraft and co)

• Specify a .map file format which is accessible (good docs) yet efficient (compressed)

gl invalid state bug

• seems to have been collision mesh's gl code, deprecated, fixed?

Mobs

Integrate GLFW windowing

Use as a default for displaying windows and manipulating context etc

SFML and SDL2 would supersede

• GLFW in project
• Add optional "window loop" to Engine just provide a display class, for a user loop like sfml
• add base example copied from sfml example (i.e. alongside sfml example)

Object Renderer

Interface ObjectRenderer with cRenderable component

Group object vertices by shader

How to link shader to component?

independent thread memory

Did not work (too slow copying)

But now CellList takes a ref to component arrays rather than all threads accessing the arrays via ObjectManager

This is much faster.

maintain one of each component array for each thread

- [ ] copy from root 🫚

- [ ] threaded operations act on their local memory

- [ ] sync back to root 🫚

- [ ] eliminates false sharing for certain

Multi-threaded Construction of Neighbour

Lists for Particle Systems in OpenMP, Rene Halver, Godehard Sutmann, 2016 : pure copy solution pretty close to more advanced
MPI solutions with threads <10

Textured Quads using Atlas textures

https://gamedev.stackexchange.com/a/174791

Texture atlas e.g n x n tiles
pass texture coords (1.0/n,1.0/n) to shader
and add offset to select correct tex coords for
requested texture

     const char * texturedQuadVertexShader = "#version 330 core\n"
    "layout(location=0) in vec4 a_position;\n"
    "layout(location=1) in vec3 a_offset;\n"
    "uniform mat4 proj;\n"
    "out vec2 texCoord;\n"
    "void main(){\n"
        "gl_Position = proj*vec4(a_offset.z*a_position.xy+a_offset.xy,0.0,1.0);\n"
        "texCoord = a_position.zw;\n"
    "}";

    const char * texturedQuadFragmentShader = "#version 330 core\n"
    "in vec2 texCoord;\n"
    "uniform sampler2D tex; out vec4 colour;\n"
    "void main(){"
        "colour=texture(tex,texCoord);"
    "\n}";

Lighting

ambient light cast by view distance

shadow quads cast by:

agent blind angles (zones)
map geometry

GL bugs in Collision Mesh's debug drawing?

• [suspected case] release build, no particles are spawned (or just not drawn?) (debug meshes)
• [case] 256 random balls, debug build, after a few seconds toggled debug, crashed on glyph texture reading (Setting data for Glyph texture 68 : GLERROR: GL_INVALID_VALUE)

Efficiency vs Composability

ECS is behind existing codes due to cost of getting components

9cd7c72 ~ 20ms for 16k and move/render systems and 3 components

8ffc0cf ~ 6ms for 16k but baked in components, so should be faster anway

benchmarks of ecs's https://github.com/abeimler/ecs_benchmark

Android Support

cTransform

For use-abilities sake the position, orientation and size have been removed from cPhysics and cRenerable
and placed into cTransform.

this aids both speed and engineering

Move bounds checking out of TileWorld into World

• move outOfBounds, pointOutOfBounds, and cameraOutOfBounds functionality to World
• merge bounds checking with Boundary object
• Test with MarchingWorld (perlin only for now) and TileWorld (map file)

window entry point undefined

demo builds from 18.04 fail on running in windows with something like

The procedure entry point
xxxbasic_stringxxx could not be located

apparently caused by an incorrect glibc and