Kright Game Tools

Introduction

KrightGameTools consists of several independent modules in Scala and C++ for 3d applications: math and physics simulation. Most Scala modules support both JVM and Scala.js.

It contains some basic classes like vectors, quaternion, matrices, and rigid body physics built on top of them. All of this is implemented from scratch and doesn't depend on other libraries. So I hope the library could be used with in graalvm or from Kotlin or Java.

All the code is under MIT license. Contributions are welcome, feel free to send a pull request.

Table of Contents

• Getting started
  • Sbt
  • Gradle
• Library modules
  • Modules
  • C++
• Tests
• How to change this library and try changes locally in other project

Examples:

1. examples/precession: Scala + sbt, simulate body precession
2. examples/nbody: Gradle + Kotlin + Java on JVM and GraalVM, simulation of N-bodies in space.
3. examples/indigodemo: Indigo game engine with scala js.
4. cpp: C++ code for 3d physics simulation.

Getting started

sbt

libraryDependencies ++= Seq(
  "me.kright" %% "gametools-mathutil" % "0.9.0",
  "me.kright" %% "gametools-vector" % "0.9.0",
  "me.kright" %% "gametools-matrix" % "0.9.0",
  "me.kright" %% "gametools-pga3d" % "0.9.0",
  "me.kright" %% "gametools-pga3dgeom" % "0.9.0",
  "me.kright" %% "gametools-pga3dphysics" % "0.9.0"
)

For Scala.js use %%% instead of %%:

libraryDependencies += "me.kright" %%% "gametools-pga3d" % "0.9.0"

Gradle:

Note: suffix _3 is for Scala 3.

dependencies {
  implementation 'me.kright:gametools-mathutil_3:0.9.0'
  implementation 'me.kright:gametools-vector_3:0.9.0'
  implementation 'me.kright:gametools-matrix_3:0.9.0'
  implementation 'me.kright:gametools-pga3d_3:0.9.0'
  implementation 'me.kright:gametools-pga3dgeom_3:0.9.0'
  implementation 'me.kright:gametools-pga3dphysics_3:0.9.0'
}

Library modules

Initially, it was a repo for simple math with matrices and vectors. I implemented physics for 3d on top of that math. During my development, I figured out that plane-based geometric algebra is a fantastic way to describe physics equations. So there is a code with geometric algebra, which includes math and physics too.

Modules

I'm inspired by https://bivector.net/PGADYN.html

I rewrote physics equations in PGA, it looks like PGA is a better way of describing physics.

• symbolic: simple implementation for AST like (1.0 + ("y" * "x"))
• ga: experimental support for geometric algebra (GA) and plane-based geometric algebra (PGA). See https://bivector.net for more details. Suitable for any dimensions
• vector: Vector2d, Vector3d, Vector4d
• pga3d: efficient library for 3d PGA with generated code and some common cases—Pga3dPlane, Pga3dPoint, Pga3dQuaternion, Pga3dBivector, etc. There is a huge number of similar methods (for each pair of classes for each type of multiplication). Because of generated methods for each case it's possible to know at compile time that, for example, dot product of two bivectors is a scalar or geometric product of two planes is a motor.
• pga3dCodeGen: hand-made code generator for pga3d module. It does operations in symbolic form, and searches the most narrow subclass of multivector for the result. Generates both Scala and C++ code.
• pga3dPhysics: some helper classes for implementing physics engine - body inertia, physics solvers, etc. Under active development now.
• pga3dgeom: classes for geometry - edges, triangles, axis-aligned bounding boxes

C++ code

• cpp: same code as in pga3d and pga3dphysics in Scala, but for C++.

The current implementation is experimental and may be changed in the future. I use C++ 20 because of Unreal Engine 5 requirements.

Tests

sbt test

I use scalaCheck and property-based approach. It goes well with checking math properties such as addition or multiplication associativity, zero and id elements, morphisms between quaternions and corresponding matrices. For physics, it's ok to check that total energy and impulse are constant in body systems without friction.

How to change this library and try changes locally in another project

Change lib code, publish to local ivy repo:

sbt publishLocal

Or to the local maven:

sbt publishM2

In my case "/.ivy2/local/me.kright/gametools-pga3d_3/0.9.1-SNAPSHOT" and "/.m2/repository/me/kright/gametools-pga3d_3/0.9.1-SNAPSHOT"

After that, add the local library to another project. In my case, it was for sbt:

libraryDependencies += "me.kright" %% "gametools-pga3d" % "0.9.1-SNAPSHOT"

And for Gradle:

implementation "me.kright:gametools-pga3d_3:0.9.1-SNAPSHOT"

Maybe you will need to remove cached lib, it will be placed in path like "~/.cache/coursier/v1/https/repo1.maven.org/maven2/me/kright/".