pgge

Pretty Good Game Engine

A 3D vehicle combat arena game built with Java 17, libGDX (1.14.2), Ashley ECS, and Bullet Physics. Targets both desktop (LWJGL3) and Android.

Started life as libGDX 3D and Bullet physics demo from "http://bedroomcoders.co.uk/libgdx-bullet-redux-2/", and modified to Ashley ECS (entity component system architecture).

Please download assets from: https://www.dropbox.com/sh/1fr6qrnrpe8bjxv/AABPse-gun_l1qdRVZQmPaJ9a?dl=0

---

Read on ... here's a project summary courtesy of OpenCode ...

Overview

• Language: Java 17
• Framework: libGDX (1.14.2) + Ashley ECS (1.7.4) + Bullet Physics (1.14.2)
• Targets: Desktop (LWJGL3) and Android (minSdk 21, targetSdk 36)
• License: Apache 2.0

Directory Structure

core/src/com/mygdx/game/
├── components/    # 7 ECS components
├── systems/       # 5 ECS systems
├── features/      # 20+ feature adaptors (game behaviors)
├── screens/       # 14 screens/UI classes
├── controllers/   # 7 input/steering controllers
├── sceneLoader/   # JSON scene loading (6 files)
└── util/          # 7 utility classes

Key Architectural Patterns

Entity Component System (Ashley)

All game objects are entities composed of components, processed by systems.

Components:

Component	Role
ModelComponent	Wraps a libGDX ModelInstance with bounding radius, animation adapter, shadowing flag
BulletComponent	Wraps Bullet physics: btRigidBody, btCollisionShape, btMotionState
CharacterComponent	Holds a SteeringEntity for AI/character behavior
FeatureComponent	Holds a FeatureAdaptor — core game-logic behavior attachment
StatusComponent	Health, damage array, bounty/points, prize count, deletion flags
PickRayComponent	Marker component for ray-casting pick detection

Utilities (in components/ package):

• CompCommon — Static helpers for spawning game objects and managing physics bodies

Systems:

System	Processes
RenderSystem	All entities with ModelComponent — frustum culling, shadows, animation
BulletSystem	All entities with BulletComponent — cleanup/disposal
CharacterSystem	All entities with CharacterComponent — AI steering behaviors
FeatureSystem	All entities with FeatureComponent — runs FeatureAdaptor.update()
PickRaySystem	All entities with PickRayComponent — ray-cast hit detection

Feature Adaptor Pattern

Game behaviors are implemented as FeatureAdaptor subclasses attached to entities via FeatureComponent. Each adaptor can define:

• update() — per-frame logic
• onActivate() — triggered by game state transitions
• onDestroyed() — cleanup on entity death
• collisionProcessor — collision callbacks

Adaptor	Behavior
BadActor	AI enemy that kills on contact
Crapium	Collectible pickup (spawns power-ups when destroyed containers)
KillSensor	Damage-dealing sensor zone
KillThing	Damage-dealing physics object
Projectile	Bullet-like projectile (ray-test movement, collision impact)
PhysProjectile	Physics-based projectile
ShootamaThing	Turret/shooting enemy
ElectricEye	Line-of-sight damage dealer
SlideBox	Pushable/movable physics block
ExitSensor	Level exit trigger
OOBSensor	Out-of-bounds kill zone
MovingPlatform	Moving kinematic platform
BurnOut	Explosion/destruction visual effect
CollisionSfx	Sound effect on collision
OmniSensor / VectorSensor	Spherical/directional proximity sensors

JSON-Driven Levels

Level data is defined in JSON files under android/_assets/_assets/screens/ (6 levels). SceneData is deserialized using libGDX's Json class and contains:

• modelGroups — Named groups of GameObjects with models, collision shapes, physics properties, and feature adaptors
• modelInfo — Maps string keys to file paths for models, textures, and audio
• features — Named game features with entity references

Screen Flow

SplashScreen → LoadingScreen(SETUP) → SelectScreen → LoadingScreen(LEVEL) → GameScreen
                                                                  ↓
                                                    MainMenuScreen (on completion)

Main Source Files

File	Lines	Role
GameWorld.java	462	Central singleton — screen management, game state, audio
GameScreen.java	631	Main gameplay — player setup, HUD, weapons
SelectScreen.java	753	Vehicle selection with animated UI
GameUI.java	629	In-game HUD, touchpad, buttons, pause menu
BulletWorld.java	370	Physics world, collision handling, ray testing
InputMapper.java	499	Input abstraction — gamepad, keyboard, touchscreen
SceneLoader.java	311	AssetManager-based loader, builds scene from JSON
GameObject.java	392	Builds ECS entities from JSON object definitions

Dependencies

Library	Version	Purpose
libGDX	1.14.2	Core game framework (rendering, input, audio, assets)
Ashley	1.7.4	Entity Component System framework
gdx-bullet	1.14.2	Bullet Physics engine (3D collision, rigid bodies)
gdx-ai	1.8.2	AI library (steering behaviors)
gdx-controllers	2.2.4	Gamepad/controller input support

Build & Run

# Desktop (960x540 window)
./gradlew desktop:run

# Build desktop distribution JAR
./gradlew desktop:dist
java -jar desktop/build/libs/desktop.jar

# Android
./gradlew android:run
./gradlew android:installDebug