todo.txt

[ ----- ----- ----- the vision ----- ----- ----- ]
In space you fly around to explore planets and star systems, and combat other ships.
For Combat/fighting, my vision is to have some elements of reactive fighter style like smash bros
where you can attack, dodge and use shield. Maybe you can upgrade your ship or swap out components
for different abilities.

In space there will be asteroids floating around. Asteroids spawn in belts around stars. Or fields floating through space.
Similar to original arcade style asteroids. Arbitrary convex polygons, but shatter in such a way that all the pieces
that break off can make up the original object. To achieve this; voronoi diagrams! A cool property of voronoi
diagrams is that the polygons it creates are always convex by nature. When an asteroid is shot by player,
create a set of random points (concentrated where the bullet hits) within the asteroids polygon.
From those points make a voronoi diagram within the original polygon, then break up the asteroid into the resulting pieces.
Those pieces can also be hit and broken down further with the same process. Until a certain threshold of
smallness where we actually destroy the object because there's no point in breaking it down further.
Upon destruction, chance to drop items/resources for the player to pick up.

Players can land on planets. Planets are generated by a tile-able noise so that the edges of the map
meet. The goal is to have a finite 2D map where you can walk continuously in one direction and eventually
come back around to where you started. This is achieved via OpenSimplexNoise, a bit of trig and modulus
magic for rendering! But there are some other technical challenges this presents that I have not yet
addressed. see https://simonschreibt.de/gat/1nsane-carpet-2-repetitive-worlds/
On the planet the player will be able to build their base. Mine for resources. Build/upgrade their ship.

Currently space is fairly empty. Worlds are very empty. Just test objects while I flesh out my ideas
and prototype systems.


MILESTONES:
 [x] started off with basic POC in a double-buffered JFrame. pure java, no libraries.
 [x] very basic physics sim with separate position, velocity, acceleration in a 0G environment.
 [x] basic polygon asteroids with simple AABB collision detection
 [x] lose the original source because I don't understand git :p
 [x] realize engines are hard, cry and move to libGDX
 [x] implement simple custom ECS
 [x] re-implement simple spaceship flight and basic asteroid polygons in new ECS style
 [x] collisions support for rotated bounding box with convex polygons
 [x] procedurally generated ship textures
 [x] basic space render system with orbiting bodies
 [x] 3D renderer for rotating 2D textures on the third axis
 [x] world render system with tiled noise
 [x] engine architecture that supports transfer between space and planets
 [x] better ECS: migrate to ashley
 [x] moved to B2D: fixed physics step and collision detection with impulse resolution
 [x] pause menu
 [x] title screen
 [x] custom shape renderer to draw filled polygons for asteroids
 [x] basic asteroid destruction using Delaunay triangulation
 [x] simple shader for star textures
 [...] basic sfx
 [ ] better asteroid destruction using voronoi

 todo: look through commits and put these in chronological order + dates?


[ ----- ----- ----- Engine Architecture ----- ----- ----- ]
This game is written in Java, GLSL for shaders, and built on top of libGDX.
libGDX is a cross-platform Java game development framework based on OpenGL (ES) that works on Windows, Linux, macOS, Android, your browser and iOS.
To get started with libGDX:
https://libgdx.com/wiki/

The engine architecture is designed around an Entity Component System. Generally:
    - Entities are composed of Components.
    - Systems operate on components.
    - Systems are managed by the engine.
Most of the game logic and rendering happens in systems.
For simplicity and consistency, components are pure data. No implementation. This may change in future.
To get started with ECS:
/~https://github.com/libgdx/ashley/wiki/Framework-overview


[ ----- ----- ----- Project Structure ----- ----- ----- ]
ECS layout: [...\SpaceProject\core\src\com\spaceproject\]
    \systems: all systems go in here
    \components: all components go in here
    \utility
        Mappers: Component Mapper Boilerplate
        ECSUtil: Some tools for managing and debugging entities

Systems are dynamically loaded and unloaded per context, as defined by @SystemsConfig:
    Space and World can have different systems.
        eg: don't need an orbit system when on a planet.
    Mobile and Desktop can have different systems.
        eg: don't need to render touch control on desktop

Data Directory [...\SpaceProject\assets]
    \config:
        One goal is to make the engine highly tune-able/configurable. (perhaps I have gone too far in this direction at the cost of complexity?)
        Plain text JSON files that define all values for game. These files will be written on first run of the game.
        if no config exists, default is loaded and written to disk. If config exists on disk, it is loaded.
        [default always loaded when debugDevForceLoadDefault = true]
        SystemsConfig: define system loading priorities and properties.
            priority: order of execution is important for game loop logic and rendering pipeline.
            haltOnGamePause: if true, system stops processing when game is paused.
            loadInSpace: if true, system will be loaded when player is in space.
            loadInWorld: if true, system will be loaded when player is on a planet.
            loadOnDesktop: if true, will be loaded on desktop platform.
            loadOnMobile: if true, will be loaded on iOS or Android platform.
        EngineConfig: define physics and rendering constants
        KeyConfig: define input keycodes
        EntityConfig: define generation parameters for entities
        CelestialConfig: defines star system generation rules
        WorldConfig: define terrain generation parameters (in progress)
        DebugConfig: defines settings like show debug rendering
        MinimapConfig: define colors and behaviors for minimap
        UIConfig: define ui element colors and positions
    \fonts: fonts for UI
        .tff   : True Type Fonts
    \shaders: GLSL shader files (name convention: reference GLSL compiler extensions)
        .vert  : vertex shader
        .frag  : fragment shader
        .glsl  : .vert.glsl, .tesc.glsl, ..., .comp.glsl compound suffixes
        .hlsl  : .vert.hlsl, .tesc.hlsl, ..., .comp.hlsl compound suffixes
    \sounds:
        Potential structure / implementation might look like: each sound effect gets it's own folder.
            - if no sound in folder, don't play
            - if one sound in folder, play that
            - if multiple sound in folder, play random
            - could allow user configurable chance? what about pitch/volume? Keep it simple...
        \music
            track a
            track b
        \effects
            \effectA
                effectA1.wav
                effectA2.wav
                effectA3.wav
            \effectB
            \effectC
    \save: (todo) serialization
        /~https://github.com/libgdx/libgdx/wiki/Saved-game-serialization

[ ----- ----- ----- Sound & Music ----- ----- ----- ]
The current upper limit for decoded audio is 1 MB.
https://libgdx.com/wiki/audio/sound-effects
* Supported Formats: MP3, OGG and WAV
    - WAV files are quite large compared to other formats
        - WAV files must have 16 bits per sample
    - OGG files don’t work on RoboVM (iOS) nor with Safari (GWT)
    - MP3 files have issues with seamless looping.
* Continuous / Looping sound 'sound.loop()'
    - raw sound file must have no gaps
    - start and end of wave should line up to prevent clipping
* Pitch: range = [0.5f - 2.0f] -> half to double frequency. Or +/- 1 octave from sample frequency:
    lower octave = [0.5 - 1.0] (eg: 440Hz * 0.5 = 220Hz)
    upper octave = [1.0 - 2.0] (eg: 440Hz * 2.0 = 880Hz)
* Panning: sound must be MONO
* Latency on android: is not great and the default implementation is not recommended for latency sensitive apps like rhythm games.
https://libgdx.com/wiki/audio/audio#audio-on-android

Given the above, sound files will be expected as:
    16-bit WAV -> MONO
    Roughly -3 to -6 db track rendering?

[ ----- ----- ----- PHYSICS CONSTRAINTS ----- ----- ----- ]
* Box2D uses MKS (meters, kilograms, and seconds) units, and radians for angles.
* Body Size Limit: Keep moving objects roughly between 0.1 and 10 meters.
* Movement limit: = 2 * units per physics step.
    * (eg step of 60: 60 * 2 = 120,  max velocity = 120km/s)
    * For the [hyperdrive] feature I need to bypass this incredibly slow limit,
      so the box2D physics body is disabled via  which means no collisions but that works in favor of gameplay.
* The fixed physics step keeps calculations frame-rate independent. (turning vsync off won't make your ship fly faster)
* Large world space coordinates will introduce inaccuracy, courtesy of floating point arithmetic rounding: epsilon.
    Floating point errors in deep space caused by large world coordinates and small frame times is affecting movement physics.
    Meaning the deeper in space we go, the more "stuff" begins to break.
    Box2D works best with world sizes less than 2 kilometers. The universe by contrast, is a little bit bigger than 2km....
    To solve this, we can use a local coordinate system and a large global coordinate system.
    todo: 'Floating Origin' ->  b2World::ShiftOrigin
    https://box2d.org/documentation/md__d_1__git_hub_box2d_docs_loose_ends.html#autotoc_md126
    https://box2d.org/documentation/#:~:text=Caution%3A%20Box2D%20is%20tuned%20for,between%200.1%20and%2010%20meters.
* Also sprites and world units: We can't use pixels for coordinates.
  https://xoppa.github.io/blog/pixels/
* Cannot remove bodies during a physics step: eg postSolve() in the physics contact listener.

NOTE: Entities should not be removed mid-frame until all systems have finished processing!
    Similarly to not removing bodies until all collisions have been processed, we remove entities at end of frame
    so that all systems can finish processing and rendering the scene.

    To remove an entity we simply add to the entity a new @RemoveComponent and entities with this component are
    removed at the end of the frame as the @RemovalSystem should always be the very last system fired.

    If a system is paranoid about execution priority and weather an entity is dead or alive,
    that system can check for the existence of the @RemoveComponent. (I haven't needed to yet in practice)

NOTE: The @RemovalSystem also handles memory management in that it will check the entity for
    data such as textures or b2D bodies and passes them off to the @ResourceDisposer to be auto-disposed.
    (this is likely a place to look during optimization, eg: things like bullets should be pooled)


[ ----- ----- ----- Size of Universe & Scale ----- ----- ----- ]
The scale of the universe is currently somewhat arbitrary as I have adjusting to the above constraints as I implement these systems.
Min/maxing the physics engine: render scale and physics bodies as small as possible to maximize the velocity limit per step.
The gameplay is mainly driven by the spaceship flight, destructible asteroids, and combat. Navigating space
and the control of the ship should feel intuitive and responsive in respect to the universe.
    * how big should a ship or player be in relation to the universe / planets?
    * asteroids: how big should asteroids be?
    * planets: how big should a planet be?
    * distances between planets: how long should the player spend traveling between systems and planets and stars?

Ultimately: Is flying around and shooting asteroids and other ships actually fun and satisfying?
It doesn't matter how big the universe is, if the local-verse isn't fun.


[ ----- ----- ----- Screen Transition + Dynamic System Loading & Unloading ----- ----- ----- ]
One of the trickier parts of the engine....
-
    I knew transitioning between space and planets would be a little tricky, memory and design wise.
    So after lots of researching design patterns, I knew an ECS would probably be the best tool.

    I make heavy use of the flexibility provided by the ability to add or remove components during run time.
    This means entities can change their behavior on the fly. This allows for dynamic behaviors that are
    completely decoupled from the entity itself.

    I originally wrote my own basic ECS implementation, but didn't want to spend time optimizing cache.
    So I migrated to Ashley for simplicity, but I would consider migrating to artemis if performance becomes an issue.
    (and I still need to pool the bullets...but first i'll build some better diagnostics tools and profile...)

    Similar to dynamic components, I also make heavy use of the ability to load and unload systems on the fly.
    This allows me to not only change the behaviors of entities at run-time, but I can dynamically
    change the behavior of the game itself by loading and unloading systems.

    Ultimately this allows me to transition between space and planets smoothly, with very little load times.
    It's not "seamless" per say, I hide the rendering system swap behind some animations. It's fairly smooth.

    I do have to be careful with managing memory such as textures when a new context is loaded and the old one is unloaded.
    I also needed it to be easily configurable as I add new systems. So I built a manager to deal with all that complexity for me.

    Maybe it's a little over-engineered, asking for memory troubles. But it works well enough so far...
-

Player first presses transition action to land or take off:
	ControlSystem()
		if in space
			landOnPlanet()
				find planet
				add ScreenTransitionComponent -> anim stage = shrink
			takeOffPlanet()
				add ScreenTransitionComponent -> anim stage = transition

When animation hits `transition` state, this calls @GameScreen to begin switching context between space and worlds.
@SystemLoader which loads/unloads relevant systems based on @SystemsConfig

	ScreenTransitionSystem()
		landOnPlanet:
			shrink: shrink ship sprite to give illusion of landing
			zoomIn: zoom in camera
			screenEffectFadeIn: fade screen to white
		-->	transition: <-- trigger @GameScreen to switch to planet.
			load: (todo: ensure planet map loaded before allowing play)
			screenEffectFadeOut: fade white back to screen
			pause: brief pause for effect
			exit: player get out of ship
			end: remove transition component
		takeOffPlanet:
			screenEffectFadeIn: fade screen to white
		-->	transition: <-- trigger @GameScreen to switch to space.
			sync: ensure find planet landed on is loaded (based on seed), ensure found and texture loaded before allowing play
			zoomOut: zoom camera from 0 to normal
			grow: grow ship sprite from 0 to give illusion of taking off planet
			end: remove transition component


[ ----- ----- -----Space Parallax Background Rendering ----- ----- ----- ]
Background color is set based on camera positioning.
Just some combinations and ratios of red, blue and green that I played around with until it looked nice.
Simple but effective: 5 parallax layers
	stars close
	stars far
	stars farther
	stars farthest
	noise far


[ ----- ----- -----  Noise Generation ----- ----- ----- ]
Noise is heavy to generate at runtime so it's done in background threads.

NOTE: we cannot generate textures in another thread due to glContext...
https://libgdx.com/wiki/app/threading
https://www.opengl.org/wiki/OpenGL_and_multithreading

We can however, generate noise data for the textures on a separate thread, and then pass the data to the rendering thread.
And we do that via a Threadpool. Once generated, it's picked up by @SpaceLoadingSystem who then creates a texture from the noise data.
You can specify how many simultaneous threads you would like to allow in @EngineConfig.
Todo: save textures/noise so it's only generated the first time. Load from disk.
For dev purposes, just generate ad-hoc for now.


[ ----- ----- ----- AI ----- ----- ----- ]
Currently primitive placeholder systems to flesh out ideas.
They can't aim properly, need to predict where player will be. Lead target.
And much more....problems for later.



:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
........................it's half in notes, half in my head, and half in code........................
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
Legend:
    [   ] = not started
    [...] = in progress
    [ x ] = complete
    [ ? ] = question
    [ ! ] = notes
    [ * ] = exceptions
.....................................................................................................

[ ] terrible BUG! Space Parallax Render broken on resolutions above 1080p
    eg: 4k or ultra wide

[ ] space station
    [x] orbit
    [ ] dock
    [ ] repair
    [ ] garage / store UI
    [ ] sell cargo for moneys

[ ] death message w/ reason:
    [ ] "stars are hot!"
    [ ] "asteroids are harder than your ship..."
    [ ] "press [] to activate your shield"

[ ] better death visual
    [ ] respawn system
        (currently handled by: [RemovalSystem] Controlled entity assumed to be player; respawning...)
        respawn at space station, docked
    [ ] emit explosion rings
    [ ] emit explosion rays
    [ ] explodey particle fx!
    [ ] maybe shatter player

[x] pickup drops from asteroids
    [x] suck into ship when near
    [x] tune it

[...] cargo
    [...] some sort of inventory
    [x] display count on UI

[x] controller input stuck on desktop until joystick moved:
    noticeable when shooting, or trying to shoot.
    see terminal for input focus -> desktop

[ ] aiming on controller is sensitive to stick drifts and twitchy inputs,
    direction facing should be average of inputs over last n frames?
    "jitter buffer"
    - in play testing this ends up being that its hard to get the ship facing the right direction
    without holding down the stick. letting off the stick can change angle facing and control
    feels not accurate to the the intentions.
    https://gamedev.stackexchange.com/questions/51081/how-to-remove-jitter-from-motion-input
    https://www.gamedeveloper.com/design/everything-i-learned-about-dual-stick-shooter-controls

[ ] swap between charge cannon and regular cannon
    [x] left right d-pad
    [x] E keyboard
    [ ] charge cannon at max shatter fully
    [ ] hold to bring up component ring

[ ] bug: control lock state during screen transition animation
    shouldn't be able to control ship during take off and landing
    [ ] should not engage jets
    [ ] should not exit vehicle
    [ ] should not shoot
    [ ] should not hyper

[ ] when take damage
    [x] red spline
    [...] snap camera
        this could be tuned a little, point is to bring attention to the fact we took damage.
        especially if we are maxed out.
    [x] vibrate controller
    [x] flash health bar
    [ ] ship body gets more red ship with health. body shader, inner black cells.
        outline shader for other states: blue shield, yellow engine, blue boost?

[x] touch the sun and die! (does not affect you during hyper)
    [x] do damage to things with health
    [x] have to use shield to protect yourself from star if you fly into it
    [?] shield heats up turns red with shader
        perhaps this could be some sort of power up?
        or need to upgrade shield to handle higher temps
        fly through the sun with shield up to absorb energy and heal?


[ ] render layer: move hyper trail layer to render when hud off

[ ] highlight planet when flying over and zoomed out to show when you can land
    glowy ring / halo

[...] hyperdrive animation
    [ ] spool up
        cancelling hyper should spool down instead of insta reset?
    [x] spin

[ ] put wings on ship

[ ] scroll should over ride reset cam

[...] terrible BUG! lerping camera movement is giving some jittering in the rendering when vsync on.
    this is caused by interpolation being a percentage from target and the value is
    shifting back and forth when near target.
    less visible when vsync off. not visible when lockedOn.
    [x] update: discovered problem:
        we want to lerp the camera for some smoothed following
        but if we lerp directly using built in camera.position.lerp()
          x += alpha * (target.x - x)
          y += alpha * (target.y - y)
        we are left from some jitter due to the lerp result being a ratio between self and target values.
        the cam position would be closer to the lerped position one frame leading to a lower value
        the next frame which in turns lags the camera and the lerp value will be higher
        leading to an ugly back and forth jitter making cam / sprites render unstable/jumpy
        solution: perform a rolling average on the lerped value over a few frames and set camera position to average.
        [ ] introduced new render issue at world border x,y < 0 when vsync off, lerp is rapidly switching between position teleporting
        [ ] camera too slow when close to lerp position -> percentage infinitely never reaching 0, should snap when close enough

[ ] terrible BUG! space loader loading and unloading system near debug origin when shouldn't
    flashes for a moment.
        [SpaceLoadingSystem] Removing Planetary System: (29993.0,29365.0)
        [SpaceLoadingSystem] Planetary System: [128818954138294](29993.0, 29365.0) Bodies: 2

[...] BUG! start game, leave to main menu, return to game: planets do not load
    [x] clean up, dispose and unload systems properly when return to main menu
    [ ] clean up threadpool, can find ways to spam fill q. not clearing properly
    [ ] things will load now, but there seems to be a strange delay...
        -start game, leave to main menu, start game again = empty until move around for a bit then loads
        I believe this is to do with the noise threads shutting down?

[ ] sound: there is no sound in the vacuum of space, therefore music sound effects are not required!
    [ ] ship impact hull and ship sounds
        [x] light: hull tapped, impulse tied to volume
        [x] heavy: ship took damage, impulse tied to volume
        [ ] alarm / hurt warning took damage
        [ ] alarm panic when health low
    [...] shield
        [x] activated, max charge
        [x] deactivated
        [x] hit, volume set by impulse
        [x] active hum while active
        [ ] alternate hum while active in star and heating up, pitch tied to heat
        [ ] shield broken, shatter / break
        [ ] charge up, pitch tied to charge
    [ ] engine / movement
        [ ] active continuous, pitch tied to velocity
        [ ] left right?
        [ ] boost
        [ ] barrel roll
        [ ] hyper drive
            [ ] charge
            [ ] discharge
            [ ] active
    [ ] rapid cannon
        [x] fire
        [ ] convert fire rate to rpm?
    [ ] charge cannon
        [x] fire - pitch tied to size
        [ ] charge up
        [ ] maxed out
    [ ] laser
        [ ] start
        [ ] active loop hum
    [ ] asteroid
        [ ] hit, volume set by impulse (how hard hit), pitch matching asteroid
        [...] shatter
    [ ] enter / exit vehicle
    [ ] transition sound
    Apparently audio on android sucks?
        /~https://github.com/libgdx/libgdx/wiki/Audio
        /~https://github.com/barsoosayque/libgdx-oboe
    More advanced audio:
        /~https://github.com/Hangman/TuningFork
        /~https://github.com/rafaskb/Parrot
        /~https://github.com/rafaskb/Boom

[ ] The player can only turn right...
    subtle yet annoying bug: when rotating continually counter-clockwise with mouse,
    once past ~7.6? radians, the ship will flip around the other way to correct.
    I suspect its to do with getAngularImpulse
    > 0
    ^ 1.6
    < 3.14
    v 4.7
    > 6.2
    ^ 7.6       <- problem
    honestly i kinda like this quirk. it makes spin outs fun. ima leave it in for now.
    edit: found it, probably the -1.57 in -atan2

[?] breaks. no more relying on debug insta stop. must have stop?
    player must not stop immediately and break momentum.
    i thing part of the charm is overshooting targets and having to fly back and correct.
    so maybe no breaks?
    [ ] X on controller

[ ] Potential optimization: don't record point on same location, or within epsilon equals
    manhattan distance^2 for faster checking. this part doesn't need to be hyper accurate
    accept for at event points (health reduced). or use optimized spines to render the path with reduced amount of data points?
    [ ] plus were not even doing frustum culling of points outside the viewport...


................above is focused on bug fix and polish phase for space demo..........................
................landing will be disabled until worlds are further developed..........................

[ ] character eye color: magenta other. red when enemy attack
    [ ] shader, eye brightness tied to health
    [ ] flash different colors and brightness at other drones to communicate
        morse code

[ ] character drone base cold resistance / heat resistance for landing on more extreme planets
    can be upgrade at garage / space station just like ship

[ ] is this why its not picking up my controller over otg on mobile?
    /~https://github.com/libgdx/gdx-controllers/wiki/Declare-game-controller-support

[...] needs frame of reference to judge speed and direction since parallax is so deep
    [...] ship tail and bullet tail fx help with frame of reference
        [ ] nicer rendering: bloom/glow, fade, colors
        [ ] optimize: reduce data points
    [ ] floaty dust particles at same depth as player to help visualize movement/speed
        perhaps play with lod, different layers based on zoom
        maybe with a very slow wander
    [ ] space debris, mostly inconsequential small irregular bodies
    [...] fog layer (particles, or white noise parallax at 1.0?)
        disabled because ugly
        [ ] could have different layers that fade in and out at different depths when zoom out
        [ ] fog layer could use some more octaves. possible shader can just render another layer on top
            with some movement and multiply the layers together
        [?] what about a basic noise shader rendered to a quad on a layer above player?

[ ] ENGINE: fix floating point errors in deep space caused by large world coordinates and small frame times is affecting movement physics: epsilon / truncating errors
    https://randomascii.wordpress.com/2012/02/13/dont-store-that-in-a-float/
    https://www.youtube.com/watch?v=mXTxQko-JH0&t=4m18s

[ ] engine architecture:
    [ ] double check use of static in gamescreen
    Caution: don’t make your AssetManager or any other resources (like Texture, etc.) static,
    unless you properly manage them. E.g. the following code will cause issues:
    This will cause problems on Android because the life-cycle of the static variable is not necessarily the same as the life-cycle of your application.
    Therefore the AssetManager instance of a previous instance of your application might be used for the next instance, while the resources are no longer valid.
    This typically would cause black/missing textures or incorrect assets.
    On Android, it is even possible for multiple instances of your Activity to be active at the same time,
    so do not think you’re safe even if you handle life-cycle methods properly!
    https://libgdx.com/wiki/managing-your-assets
    [ ] Memory leaks
    theres a lot of new Vector3 in core loops. -> cache / pool

[x] add basic asteroids (arbitrary poly)
    [x] spec spawner for asteroid.
        - asteroid source A: belt / circumstellar disc
          a ring of random destructible asteroids around a planet
             belt radius: range from source body
             belt width: how wide bodies spawn from concentration of bodies at belt
             belt density: how many asteroids to populate belt with
             direction: which way they orbit around body
        - asteroid source B: "field" / cluster
          random group out in the depths of space
             pocket size: how many to spawn in group
             direction: which way headed
        - asteroid source c: rogue rock "odd ball"
             just a single rock of random size maybe larger than usual, going in a random direction
        - if any asteroid is too far from player, unload
    [...] belt - ring around barycenter component
        todo: apply gravity to keep them rotating around star
        problem: we want asteroids to spawn in rings and stay in rings generally, but allow player to shoot them out of belt.
        I can't let the bodies float around freely with a simple n body sim as they are not stable.
        the system will just tear itself apart. even if a "stable" orbit is found it will become unstable as the player starts interacting with it
        currently this is why planets are locked in an elliptical orbit to sort of fake gravity.
        do I lock the asteroids in orbit similar to the planets? maybe interpolate to where they "should" be, pulling them back into the ring
        maybe once hit or disturbed, loses orbit component and floats freely?
        basically it comes down to how "arcadey" vs "simulator" does it need to be fun?
        currently there is no friction and we have conservation of momentum
        plan of attack: i think i will start off with a lie, lock them in orbit when spawn.
        once disturbed or interacted with by an outside force, unlock the orbit and let gravity take over
        allow belt to "chain react" collapse / disperse and see what that plays like
        [ ] orbit with flocking / group mechanic?
            currently broken: flings out into space
    [x] field - randomly spawn while in space
    [x] begin make asteroid
        [x] attach box2D poly to match asteroid poly
            [x] fix center of gravity
        [x] take damage when hit by shots
    [ ] better rendering. currently just debug render with modified shaperenderer
        [...] display health/damage on asteroid
            [x] colorize by damage/health for visual feedback
            [ ] draw cracks / sub poly
        [ ] set a texture to take up the dimension of an arbitrary poly
        [ ] sub shatter texture to child polygons scissors?
    [...] break into smaller asteroids
        [ ] BUG: sometimes shatter creates way more child bodies than it should, like 2 or 3 times the pieces
        [ ] BUG: sometimes bodies disappear instead of shatter
        [ ] tune!
            -shatter difficulty: how many shots to break, how hard impact to break
            -density: weight and feel of how bodies impact eachother and player
            -shatter mechanics pass down extra damage to children?
                eg: asteroid has 100 hp, breaks into 2 = 50hp children
                  damage 110 = -10 hp, breaks into 2 minus 5 each = 45hp
                  damage 200 = -100 hp, breaks into 2 minus 50 = 0hp = don't spawn children -> instant destruction
                 could play with different rules and ratios, find what feels good
           -shatter style (asteroid type): triangles, evenly, grid, arbitrary geometry. eg: rock shatters different than ice (material properties)
            rock: larger pieces widely spaced more voronic with concentration of points at impact location
            ice: more crystalline shards / slivers
            crystal: evenly spaced geometrical shards: eg hexagons
        [x] should not display health bar on asteroids
        [ ] some visual feedback for damage like cracks would be nice: could use voronoi edges as cracks
        [ ] polygon slicing! ability to cast ray through asteroid and have it split on intersection
            would be useful for laser weapon
        [x] basic triangle shatter
            [ ] broken rotation when shattering some polygons rotate and jump instead of simply separating in place
                note: this is more visible with vsync off.

        [ ] voronoi shatter, for destructible asteroids.
            (and world generation can be used for tectonic plates / countries / biomes)
            https://www.badlogicgames.com/forum/viewtopic.php?f=11&t=22784 (my old thread)
            /~https://github.com/mjholtzem/Unity-2D-Destruction
        	http://www.alanzucconi.com/2015/02/24/to-voronoi-and-beyond/
        	https://stackoverflow.com/questions/20104779/libgdx-create-texture-from-overlay-using-pixmap
        	https://pvigier.github.io/2018/11/18/fortune-algorithm-details.html
            http://www-cs-students.stanford.edu/~amitp/game-programming/polygon-map-generation/
            https://leatherbee.org/index.php/2018/10/06/terrain-generation-3-voronoi-diagrams/
            texture and create child bodies from parent:
            https://www.emanueleferonato.com/2012/01/17/create-real-explosions-with-box2d-adding-textures/
            https://www.emanueleferonato.com/2012/03/05/breaking-objects-with-box2d-the-realistic-way/
            https://thebookofshaders.com/12/
            https://www.youtube.com/watch?v=4ySSsESzw2Y
            https://www.youtube.com/watch?v=jxOAU7YfypA
    [x] damage vehicle on high impact

[ ] JUICE!
    https://www.youtube.com/watch?v=Fy0aCDmgnxg
    https://www.youtube.com/watch?v=tu-Qe66AvtY
    [x] lag camera behind movement a little for visual effect, especially when dodging for more visual impact
    [x] change cursor to a crosshair sprite
    [...] camera allow cursor to "extend view": pushing cursor to edge of screen pulls camera position at a point between player and mouse
    [...] camera: combat camera
        manually zooming in an out when fighting is a bit clunky and jarring.
        [x] implement an auto lock on camera which will adjust the zoom to include both the player
            and the enemy within frame
        [ ] always keep player in frame no matter what
        [ ] tuning: when entities too far apart or too out of frame, return to focusing on player
        [ ] tuning: lerp between locked on state and player focus
        [ ] consider multiple enemies, 3 on screen? include all will make zoom far and less focused, so probably some sort of
            dynamic focus, maybe who gets shot last has focus? todo: study cam mechanics for smashbros / project m style combat
            thresholds for how close to focus near the edge
        [?] still allow manual override with scroll, with perhaps a timer to focus back in, or when a new enemy joins
    [ ] while im no artist, i think picking a color palette might make it look a world and ui a little more consistent
        http://devmag.org.za/2012/07/29/how-to-choose-colours-procedurally-algorithms/
        [ ] the space ships need more contrast from space background
            add a 1-3 px dark pixel drop shadow around edges of ship as part of the raw ship image
    [ ] lighting!
        simple "cheat" use sprites: https://www.youtube.com/watch?v=fsE1ddOas7A
        /~https://github.com/mattdesl/lwjgl-basics/wiki/ShaderLesson5
        /~https://github.com/mattdesl/lwjgl-basics/wiki/OpenGL-ES-Blurs
        /~https://github.com/mattdesl/lwjgl-basics/wiki/2D-Pixel-Perfect-Shadows
        box2d lights /~https://github.com/libgdx/box2dlights
        [ ] engine fire can be a light source
        [ ] shield can be a light source
        [ ] player eyes facing forward cone light
        [ ] lava on planets can be a light source
        [...] ship / wind trail system to visualise movement
            [x] debug just draw path?
        [ ] ship wing tips blink with lights, or light source on texture (simply a image overlay)

    [...] better star rendering
        [ ] gaussian blur, write star to buffer.
            use gdx-vfx, stop reinventing wheels
            /~https://github.com/crashinvaders/gdx-vfx
        [ ] smooth out image
            could extend the source star radius on texture (or simply full rectangle), then simply set the alpha drop off in the shader
        [ ] could shift the noise vertically and horizontally
        [ ] shift should go continually outward, not roll back inward (sinewave)
        [...] better colors
            [x] give stars random temperature between: 1000 - 50,000 Kelvin
                "Stars vary in surface temperature from about 2,000 to 40,000 kelvin"
                Harvard spectral classification
                O	≥ 33,000 K 	        blue
                B 	10,000–33,000 K 	blue white
                A 	7,500–10,000 K 	    white
                F 	6,000–7,500 K 	    yellow white
                G 	5,200–6,000 K 	    yellow
                K 	3,700–5,200 K 	    orange
                M 	2,000–3,700 K 	    red
                R 	1,300–2,000 K 	    red
                N 	1,300–2,000 K 	    red
                S 	1,300–2,000 K 	    red
                https://simple.wikipedia.org/wiki/Stellar_classification
            [x] Make function to convert temperature to color
                Wien's Law: tells us that objects of different temperatures emit spectra with peaks at different wavelengths.
                    Hotter things - peak at shorter wavelengths - bluer
                    Cooler things - peak at longer wavelengths - redder
            [ ] luminosity?
        [ ] could add more noise layers: octaves
        [ ] needs flames n solar flares!!!
            fire: https://stegu.github.io/psrdnoise/2d-tutorial/2d-psrdnoise-tutorial-20.html
            [ ] some sort of texture / shader to make firery splines
            [ ] outward firing firery particles
        [ ] varying brightness, twinkle by increasing decreasing brightness pseudo-random sine wave, or rather 1d noise
        [ ] lighting. sun as source of light lighting up planets and ships around it
            [ ] apply shadow on side of planets not facing star
                [ ] could even do eclipse if another planet / moon in between star
            [ ] apply light source on 3D models would make 3D barrel roll rotation more clear with shadowing
        [x] it's currently static just like planets, but I want it to shift the z, exactly like the title screen background
            com.spaceproject.screens.animations.NoiseAnim
        could be done on gpu even:
            https://www.shadertoy.com/view/XscGzl
    [ ] better planet rendering
        inspiration: /~https://github.com/yurkth/astraea
        [ ] nearby stars can be light sources, shade side not facing star
    [ ] SHADERS!!!
        [ ] when entity hit, sprite needs to flash red or white -> shader
        [?] 2D outline shader for ships and mouse over objects
            http://www.allpiper.com/2d-selection-outline-shader-in-libgdx/
            https://www.youtube.com/watch?v=1yuYUVFUOvI&list=PLqpawGIg6Qj5CvjOaCbB536z862XhjPQi&index=17
    	/~https://github.com/mattdesl/lwjgl-basics/wiki/Shaders
    	/~https://github.com/mattdesl/lwjgl-basics/wiki
    	https://www.shadertoy.com/view/XscGzl <--use for stars
    	http://www.alanzucconi.com/2015/07/01/vertex-and-fragment-shaders-in-unity3d/
    	http://www.alanzucconi.com/2016/01/27/arrays-shaders-heatmaps-in-unity3d/
    	http://wwwtyro.net/2016/10/22/2D-space-scene-procgen.html
    	https://thebookofshaders.com/


[...] rendering system
    [ ] tune camera: https://www.youtube.com/watch?v=aAKwZt3aXQM
    [ ] decouple HUD from stage -> move scene2D stage out of HUD into own system
    [x] fix space parallax system rendering
        [x] background layer stars are just white currently
            give them a random temperature then convert wavelength to rgb: Black body radiation!
        [x] i think it needs to be rendered with a separate camera / viewport as to not zoom out with main camera
            the background space image needs to be "very far away", give the illusion.
        [ ] generating pixmaps on the fly is slow.
        [?] option 2: replace with shader?
            maybe something like this:
            https://www.shadertoy.com/view/ltXSDN
            https://www.shadertoy.com/view/ldKGDd
            https://gamedev.stackexchange.com/questions/146098/2d-parallax-scrolling-through-glsl-shader
            https://badlogicgames.com/forum/viewtopic.php?f=11&t=11419
            or something like this:
            https://wwwtyro.github.io/space-2d/
            /~https://github.com/wwwtyro/space-2d
            [...] POC star shader with fullscreen quad in separate project
                /~https://github.com/0XDE57/gdx-shadertoy
                should I render to a square fbo? then the fbo texture can scale to the viewport without distortion?
                    helpful for porting shadertoys to libgdx:
                                    https://gamedev.stackexchange.com/questions/186477/why-dont-shadertoy-shaders-work-with-libgdx
                https://www.youtube.com/watch?v=rvDo9LvfoVE
                [OUT_OF_SCOPE] Bonus would be reallly cool but overkill would be to feed audio track into
                the shader so it can react to the music. apply FFT -> visualizer. pulse stars to the beat?
        [x] background space color fade to black when zoom out (temporary until better space background approach is implemented)
        [x] experiment: can we make the background tiles just not zoom out? use a different batch perhaps?
    [...] fix render priority (z-order)
          [X] moved into separate variable
          [x] define proper heights for importance as current values are somewhat arbitrary
          [?] this is now a bit more complex, as there is a mix of 2d sprites and 3d renderables, that are rendered in separate batches (2d then 3d overlay).
              to mix the z between them may require multiple batch passes, or migrating to 3d, also shaperenderer on top of that...
              custom shape renderer?
              if we are doing too much batch flushing could use (bonus if could do outlined shapes, perhaps a job for a shader instead?):
              /~https://github.com/earlygrey/shapedrawer
    [ ] its really hard to see ships when zoomed out.
        look into homeworld - style NLIPS, or non-linear inverse perspective scaling

[...] respawn
    [x] for now, just place back at origin 0, 0
        [ ] nearest planet
    [ ] move into own system
    [ ] how to handle death? start on planet back at base? start at a space station?
        [?] could have a "home planet" and just spawn from there like transitionsystem takeoff
        [?] base space station that has its own orbit around either planet or star. dock to space station

[ ] AI
    Current AI is very primitive placeholder.
    /~https://github.com/libgdx/gdx-ai/wiki
    [ ] lead shot, projectile prediction
    [ ] when player dies, notify AI that are stuck attacking nothing and should return to dumbwander or previous task
    [ ] #Arrive for landing on planets: arrive at the target position with a zero velocity.
    [ ] Heat system? Attacking another ship will bring heat on yo ass.
        Other ships will spawn from nearby planets or space stations after you.

[...] shield
    [...] if collide with bullet, shrink/destroy shield
    [x] shield should protect from high impact collisions. otherwise do damage relative to how hard impact.
        eg: ram ship into an asteroid at high velocity could destroy ship, use shield before impact to bounce off
        [ ] if hit is hard enough, break shield
            add new broken state with cooldown
        [ ] shield dash bash? high impulse forward, then activate shield to ram other objects and do damage to them
    [x] fix radius is not consistent. rotation of body affects size of shield. don't trust calculateBoundingBox()?
    [x] shield growth overrides and cancels charge cannon
        [ ] since we built up the energy in our cannon, it should transfer to the shield for insta charge!
    [ ] grow/shrink body with shield. looks like cant resize bodies in box2d? destroy and recreate each frame seems inefficient likely
    [x] bug not render on planet
    [ ] graphics: rotate shield polygon, possibly a shader to make edges glow: BLOOM!
    [x] should be unavailable during hyper drive
    [ ] should not activate during screen transition
    [ ] needs control for mobile

[...] barrel roll
    [...] adjust feel, impulse, tuning
        [ ] boost flame should be bigger than regular, maybe additional particles?
        [ ] forward + side boost should make diagonal impulse 45 between engines
    [x] change engine particle effect color when dodging / boosting
        [ ] should only change for boosted engine, not all active, unless all boost
        [?] should boost forward and sideways add impulse from both axis
            at reduced power shared between? = 45 degree angle impulse
    [x] apply forward force similar to dash with same impulse power
        [ ] should just go forward when alter hit, no need for alter. to be more coherent with dash.
            rename alter as boost?
    [?] allow roll on other axis? could allow for front/backflips. also, could use other roll parameter for animation
    [x] when hit by projectile, roll the body a bit, then the roll system will stabilize it back
        for impact feel
    [x] should not activate while using shield
        [?] should allow while shield is discharging? might feel more responsive
    [x] should not activate while hyperdrive active
    [ ] should not activate during screen transition
    [ ] needs control for mobile

[x] character dash
    [ ] some sort of visual elements to show speed / motion: eg dust cloud at feet or whooshy lines

[...] grow cannon
    [x] BUG: charge cannon should always fire when trying to fire instead of waiting for minimum charge (cooldown between shots instead of build up until can shoot)
    [x] BUG: when entity is killed/removed during charge, charge cannon and particle remain instead of being removed
    [ ] should be circle instead of rectangle?
    [ ] should change color when maxed
    [ ] lock on nearest target when maxed
        [ ] visual in hudsystem for tracked entity
        [ ] predict angle to aim to hit based on pos and velocity
        [ ] steering behavior AI?
    [?] could perhaps shrink "lose energy" over time and destroy self when smaller than threshold
        only maintains size when fully charged to max
    [ ] AI doesn't know to release grow cannon, only tuned for regular cannon
    [ ] should not fire during screen transition

[ ] hyper drive
    [x] hyperdrive should be hold key to charge up instead of instant activate
    [ ] change hyperdrive to only work when maximum speed. this does 2 things:
        a: more intuitive, removes a button = less complexity. just keep going fast when move = makes sense.
        b: prevents rapid toggle on and off, have to be going fast is more interesting
        when at max speed, charge up hyperdrive energy until max, then once reached will engage
        any action like trying to move or shoot should disengage hyperdrive
        this should also activate a small cool down in which the ship cannot activate sheilds or shoot
    [ ] non-UI charge up indicator, eg: engines spin up, ship glowing or something
    [ ] charge up sound effect
    [ ] discharge sound effect
    [ ] different particle effect for when active
        [x] different color particle effect for fire. different from normal and boost. maybe purple or green?
    [ ] blur passing by background stars as if not clearing screen between frames: streaks
    [ ] tune feel: give more impact
        [ ] maybe some screen shake during
    [ ] potential for playing with some shaders

[ ] laser
    [ ] you are the laser! hyper drive
    [ ] cut asteroids, arbitrary polygons in half
    [ ] ray case polygon collision to stop head of lazer at object
    [ ] render technique? sprites or shader? for now just shape renderer
        [ ] programmatic color and width

[ ] glow / lighting
    shaders vs sprites
    texture mask with alpha that fades towards edges
    bloom?
    emission map?
    https://www.youtube.com/watch?v=WiDVoj5VQ4c


[...] particle effects!
    /~https://github.com/rockbite/talos
    [ ] BUG: broken engine effects applying to other ships when land on planet
        [ ] BUG: related, when take off again particles are wack!
    [x] projectile tails - simple rect or circle particle trailing bullets
        [ ] apply to other cannon
    [x] particles need to render on top of planets. planets should be first rendered (low depth) in the render pipeline
    [x] particlesystem and emitter components
    [x] rendering is lagging behind camera "drift bug" -> refactor rendering/system order.
        looks fixed when vsync off
        [x] split into update and render? fixed!
    [x] absorb effect when charging charge cannon
        fixed! solution -> attached: true in *.particle
            - Options -
            attached: true
        [x] should not drift when rotating
        [x] should not drift when moving (absorb, locked to charge itself, not relative to ship movement?)
            particle should chase bullet instead of moving towards spawn origin which is no longer the bullets location
    [ ] alternate engine particle effect when hyperdrive active
    [ ] absorb effect when charging shield
    [ ] charge burst effect when bullet destroyed (absorb reversed)
    [ ] shield burst effect when hit by bullet and shield destroyed
    [ ] explosion effect on ship destroy
    [ ] some particles on projectile destroyed/removed
    [ ] scale engine particle emission or velocity by movement multiplier
        - Emission -
        lowMin: 0.0
        lowMax: 0.0
        highMin: 250.0
        highMax: 250.0
        relative: false

[ ] controls and input
    [...] need a better slow down / stop. perhaps a reverse force, and point side engines forward 45
        [x] this control should also exit hyper drive
        [ ] how does this feel with controller? needs moveBack control
    [x] basic controller input
        [?] should separate look from movement? meaning movement left stick, aim/look right stick
            might make sense for on foot character (could separate look and movement on MnK too)
            this would displace the camera zoom control. we could let it modify camera with a modifier? eg: d-pad left + right stick
            would probably make mobile control more difficult (two virtual sticks)
        [ ] scene2d stage (main menu and pause menu) needs to support controller input. multiplexer?
            /~https://github.com/MrStahlfelge/gdx-controllerutils/wiki/Button-operable-Scene2d
        [ ] also keyboard navigation focusable items
        [x] tested with xbox 360 wired and ps4 controller over usb
        [x] allow hot-plugging
        [x] crashes title screen after return to menu from game, looks like systems still loaded (unhook listeners?)
            cant repro, seems fixed. update: still crashes!!! update: fixed again.
        [x] basic Xbox 360 support
            [x] not detecting DPAD buttons
            [x] double tap right left bumpers for barrel roll
            [x] right stick camera control, click to reset
                [ ] tune: doesn't feel smooth when stick all the way in or out.
                    adjust curve to stick in amount
        [x] move to getMapping() but seems im on an older lib?
            /~https://github.com/MrStahlfelge/gdx-controllerutils/wiki/Configurable-Game-Controller-Mappings
            /~https://github.com/libgdx/gdx-controllers/wiki/Migrate-from-v1
        [?] right trigger boost, similar to roll impulse?
        [ ] left trigger for break / slow down
    [ ] keyboard navigation for menus
            [...] debug menu
            [...] main menu
                [x] hotkeys
                [ ] navigation and selection
            [ ] title menu
    [ ] mobile
        [ ] if player bounds overlap vehicle, show enter button on touchUI/hud
        [ ] if in vehicle show exit button (if can get out? must be over platform/spacestation? jetpack?)
        [ ] pinch-pull to zoom in-out on touch
        [ ] test touchUI on different screen sizes/resolutions
        [ ] set engine speed max to multiplier on android?
        [ ] hyperdrive needs control for mobile
        [ ] dodge/barrelroll needs control for mobile
        http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/input/GestureDetector.html
        http://tutorial-libgdx-android.blogspot.com/2014/02/inputs-handling-1st-part.html
    [?] shield bash?: double tap forward(or direction) and hold to rush, then shield do shield action [B] within time window of dash, and hold
    [?] land take off could be hold instead of instant
    [ ] landing should be easier, when in range of planet (larger radius than planet itself)
        [ ] should not be relying on debug instant stop control, breaking needs to be better / smoother
        - additional animation step, autopilot. instead of instant stop
            - calculate () required angle and velocity to aim at center of planet
            - automatically apply correct force to steer efficiently/accurately
            - face opposite of velocity (aim for planet)
            - hard engine blast to slow down fast, calculate relative velocity to apply correct force
            -
        - ensure AI can't overshoot
        /~https://github.com/libgdx/gdx-ai/wiki/Steering-Behaviors#arrive
    [ ] getting into ship sometimes a little clunky, switch from distance check to sensor
        add sensor to player
            if contact has ship component, get in.
        could also hand generic interactions if contact has intractable component, do whatever interact action
        collision callback can also solve mobile ui for vehicle button:
            BeginContact:vehicleButton.enable()
            EndContact:vehicleButton.disable()
        http://www.iforce2d.net/b2dtut/sensors


[...] physics and movement
    [x] move to box2d
        [x] move logic to new physics
        [...] figure out scales and values that make sense and work with the b2d engine (consider scale of space)
            [ ] create unit/body scale helper
        [ ] move to filters?
            http://www.iforce2d.net/b2dtut/collision-filtering
            https://gamefromscratch.com/libgdx-libgdx-tutorial-13-physics-with-box2d-part-4-controlling-collisions-using-filters/
            https://www.youtube.com/watch?v=IIZ7XI6L7IA
    [x] fixed time step (necessary for multiplayer?)
        [ ] interpolation
        /~https://github.com/libgdx/ashley/pull/215
        /~https://github.com/libgdx/ashley/pull/216
        https://gafferongames.com/post/fix_your_timestep/
        http://gameprogrammingpatterns.com/game-loop.html
        http://www.koonsolo.com/news/dewitters-gameloop/
    [?] how to better handle collision system telling other systems what to do?
        https://gamedev.stackexchange.com/questions/23834/how-to-properly-implement-message-handling-in-a-component-based-entity-system
    [?] note to self, was my old physics broken due to #5048?
        I dropped my physics because the impulse was so weird, i did infact use Intersector.overlapConvexPolygons() in CollisionSystem.java.overlaps()
        /~https://github.com/0XDE57/SpaceProject/blob/1a764f9aaa405ba18341ad35c2a75b4ecd02a535/core/src/com/spaceproject/systems/CollisionSystem.java
        [ ] todo: confirm that im not crazy? because i spent a lot of time moving to box2d if this is true lol.... thats ok.

[...] screen transition between world and space
    [ ] ready / sync / load state. should all be in transition system?
        still a little coupled, but working reliably now
        [ ] WorldRenderingSystem shouldn't be responsible for loading map: loadMap().
    [ ] landing animation should center camera focus on midpoint between planet and player
    [ ] better take off animation
        [ ] should have ship leave ground camera stays put, create a shadow sprite underneath for depth
        [ ] ship can fly off screen, camera stays put, zoom out.
    [?] should not be loading system near origin, position needs to shift to last known planet BEFORE SpaceLoadingSystem picks it up
        [SystemLoader] systems loaded in 1ms
        [SpaceLoadingSystem] Planetary System: (1000.0, 1000.0) Objects: 8
        [ScreenTransitionSystem] Animation Stage: sync for Entity@7440577b
        Forget the context of this bug, it is happening when leaving planet far from origin?
    [x] finish transition animation, should have screen effect for polish and to hide loading/level change. goal feel a little more seamless
        (fade to white/pixelate shader during landing, load map (can wait here for a second if not finished generating, when generations finished start white then fade normal, continue)
    [x] bug: had an instance where take off rogue planet ended up with no ship and seemingly wrong co'ords
        see: ScreenTransitionSystem.syncLoadPosition()
    [x] bug: landing and take off unreliable for systems away from origin, location not saved / set when land
        cannot find seed
        cannot find seed
        cannot find seed
        this bug is driving me insane, but there's still some transition and loading details to work out
        fixed!...but keep and eye on it.


[...] fix texture / map loading
    [ ] save load noise so it doesnt have to be generated
    [ ] clean up star save/load
    [!] bug: when play with generation settings in TestNoiseScreen, seems to effect map/tile generation in game
        ! actually for now this is a convenient bug for testing



[ ] devmode and play mode
    [ ] DevMode
        -dont load save files
        -hardcoded seed
        -forced test entities
        -forced close star system
    [ ] PlayMode
        -load save
        -random seed
        -no hardcoded entities. entities should come from spawning systems instead
    [ ] new CombatTest debug screen for prototyping combat and movement mechanics and feel
        [ ] player vs AI
        [ ] AI vs AI


[...] Space Ship
    [...] COMBAT
        [...] 3D roll animation for dodge / barrel roll
                [...] scale bounding box during rotation
                [x] adjust feel, it doesn't quite feel very dodgy, maybe try lagging the camera behind the roll
                [ ] clean up: should move values to config
                [ ] clean up: optimize rendering -> ModelCache
                [ ] mobile/touch UI way of activating dodge, a swipe on the joystick may be intuitive
        [ ] bullets should come from a gun rather than magically from ship
        [ ] weapon types
            [x] basic cannon
            [x] grow cannon shoot circles/rectangles with radius relative to damage "weight" of projectile (damage = size * velocity * typeMultiplier)?
            [OUT_OF_SCOPE] L cannon, touhou style multiple bullet cannon
            [OUT_OF_SCOPE] Laser cannon
    [ ] engine mode:
            [x] local/combat (slow, for interacting with object near, landing planets, fighting)
                defined as max 60. over goes to cruise mode
            [...] travel/cruise (medium, for navigating within a system, planet to planet, avoid/escape, faster travel)
                defined as 60 - 120. 120 is box2d engine max with current physics settings.
                use of shield or weapon should auto return you to combat speed
            [x] hyper/warp   (fast, warp to other systems, can't turn, can't fight)
                activated by [T]

    [OUT_OF_SCOPE] ship generation
        [ ] fix ship edges to use entire width of texture
	    [...] wings
	    [ ] engines
	    [ ] weapons
	    [ ] details: eg: lines, another layer on top for depth/windshield type thing, different stuff on underside of sprite
	    [ ] generation styles and classes, perhaps come up with some kind of classes of ships (cargo, highspeed traveler, tank/war machine, passenger, personal, commercial...)
	    inspiration:
            http://davebollinger.org/works/pixelspaceships/
            https://www.reddit.com/r/gamedev/comments/2tavse/2d_procedural_spaceship_generator/
        [ ? ] do we give up on proc gen and modular ships and go with something like:
            https://livingtheindie.itch.io/pixel-art-spaceships-for-shmup

[...] planet generation
    [ ] player could use more contrast against the planet
        shadow back drop?
    [ ] a cloud layer above planets
        noise texture shifting across
    [ ] we could render the planets as actual torus. since we already have the 3D render system
        we find a way to map texture to a torus
        https://stackoverflow.com/questions/29953874/how-to-texture-of-a-glutsolidtorus-in-opengl
        https://mathematica.stackexchange.com/questions/103215/map-points-on-a-square-onto-a-torus
    [ ] grid based loading 3x3 tiles with "bleed area" margin: leeway/tolerance for loading when on edge.
        so that tiles aren't constantly loading or unloading when walking along edge between tiles.
    [ ] research planet attributes //size, temperature, pressure, atmosphere/elements(https://en.wikipedia.org/wiki/Astronomical_spectroscopy)...etc
        https://en.wikipedia.org/wiki/Circumstellar_habitable_zone
        [ ] add temperature variable to planet determined by distance from star
        [ ] for now simple linear, close to planet = hot, far from planet = cold
        [ ] if want more advanced, have star temperature based of distance from galaxy center
            then that would also affect star temperature.
            for inspiration see:
                https://beltoforion.de/en/spiral_galaxy_renderer/spiral-galaxy-renderer.html
                https://beltoforion.de/article.php?a=spiral_galaxy_renderer
                /~https://github.com/beltoforion/Galaxy-Renderer
        [ ] hot planets can be lava / deserts, cold planets can be ice n snow.
            stuff in between can be "normal" (green, water, etc)
        [ ] sand planet with sandworms, like dune.
    [ ] rivers and other terrain features
    [ ] biomes
	[ ] rings around planets (like saturn)
	[...] moons
	    [ ] orbit distance for moons should not have overlapping rings with previous orbit path, spacing needs to include children
            also consider asteroid belts
	[ ] satellites
	[...] wrap planets properly (LOCAL COORDINATE SPACE?)
        https://www.reddit.com/r/gamedev/comments/1gi6np/magic_carpet_style_infinite_wrapping_terrain/
        https://simonschreibt.de/gat/1nsane-carpet-2-repetitive-worlds/
	inspiration and references:
	    Noise-Based RNG: https://www.youtube.com/watch?v=LWFzPP8ZbdU
	    http://www.entropicparticles.com/6-days-of-creation/
	    https://plaxdev.wordpress.com/2017/05/04/procedurally-generating-islands/
	    https://www.reddit.com/search?q=%28perlin|simplex|opensimplex%29+noise&sort=new
	    http://ronvalstar.nl/creating-tileable-noise-maps/ <--looping noise
	    https://www.gamedev.net/blog/33/entry-2138456-seamless-noise/ <--looping noise
	    https://gamedev.stackexchange.com/questions/23625/how-do-you-generate-tileable-perlin-noise <--looping noise
	    http://developworlds.com/blog/2015/05/28/procedural-tilemap-generation/
	    https://flafla2.github.io/2014/08/09/perlinnoise.html
	    http://devmag.org.za/2009/04/25/perlin-noise/
	    http://blog.kaelan.org/randomly-generated-world-map/ <--biome
	    http://freespace.virgin.net/hugo.elias/models/m_perlin.htm
	    OpenSimplex: https://gist.github.com/KdotJPG/b1270127455a94ac5d19
	    new KdotJPG noise!: /~https://github.com/KdotJPG/New-Simplex-Style-Gradient-Noise

[ ] space stuff
    [ ] various astronomical bodies
        https://en.wikipedia.org/wiki/Astronomical_object#Categories_by_location
	[ ] stars kill on touch (hot!)
	    unless maybe you have an upgraded ship that can handle it?
	[ ] wormhole (teleport)
	    [ ] for now just render a circle
	[ ] blackhole (death)
	    place at center of galaxy
	    https://www.shadertoy.com/results?query=black+hole
	    https://www.shadertoy.com/view/ldy3zK
	    https://www.shadertoy.com/view/ltBGWh
	[ ] dust/noise
	[ ] light specs/debris,details
    [...] galaxy generation inspired by fibonacci spiral
        [...] test screen to generate spiral
        [ ] generate set of points that are concentrated near center, and near arms of spiral
        [ ] implement generation into game
        [ ] make a screen animation


[ ] UI
    [ ] edge map improvement, when entity facing a mapable component (with a few degree wide threshold)
        - make bigger as if focused
        - display distance
    [...] map
        needs more details, select planets and get info, set way points
        [ ] minimap should show heightmap of world when on planet
            (fog of war) start out with grayscale pixelated version, when area visited then render full map and color
    [...] menu menu
        [ ] window snap left right
        [ ] change mouse cursor when over resize,
        [ ] visui resize is only 1px wide = very hard to use
        [x] pause / freeze game
        [...] settings and config
    [ ] player manager/inventory/shipbuilder thingy
    [ ] career event timeline stats

[x] warning when launch
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.lwjgl.LWJGLUtil$3 (file:/home/logica/.gradle/caches/modules-2/files-2.1/org.lwjgl.lwjgl/lwjgl/2.9.3/3df168ac74e4a8c96562cdff24ad352e255bf89c/lwjgl-2.9.3.jar) to method java.lang.ClassLoader.findLibrary(java.lang.String)
    WARNING: Please consider reporting this to the maintainers of org.lwjgl.LWJGLUtil$3
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    closed #1

[ ] get rid of bar thing on fullscreen android
    useImmersiveMode? see: #6683

[ ] devops n website n legal crap n misc
    [  ] prepare to branch and have a dev stream and "stable stream"
        i need to learn git properly, im lazy just click the button
        https://ohshitgit.com/
    [ ] what are requirements to release on Steam?
        [ ] do I need to trademark / copyright anything?
        [ ] do I need to that ersb rating thingy?
    [x] move to LWJGL 3?
        https://libgdx.com/news/2021/07/devlog-7-lwjgl3
    [ ] move this todo list thingy to a trello or something?
    [ ] need an icon. its still the default libgdx logo...
    [ ] make a page for website spaceproject.xyz or make a github io?
        [ ] dev blog thingy?
    [ ] wiki n documentation
    [ ] should prolly make some unit tests at some point...
    [ ] legal crap?
        https://www.youtube.com/watch?v=8eAW-7Js7NA
        https://www.youtube.com/watch?v=t8UFJ3obm-Q
        https://www.youtube.com/watch?v=ePQcAjuiSEo
    [ ] build signing
        https://developer.android.com/studio/publish/app-signing

[...] config
    [x] config manager, save and load all configs
    [...] config UI
            [OUT_OF_SCOPE] nice way to view and edit configs
                [ ] fix layout
                [ ] hook up load save undo
    [OUT_OF_SCOPE] figure out serialization
        [?] Ships are currently hardcoded by Entity factory
            can we find a way to generate entities from config.
                - consider ranges,
                - consider space vs planet differences (eg: physics)...
                - consider mobile vs desktop? maybe?
            eg:
            Ship {
                SeedComponent{},
                TransformComponent {

                },
                Sprite3DComponent {
                    shipSize = rand range(x,y)
                }
                PhysicsComponent {
                    linearDamping, (when on planet, will be 0 in space)
                    angularDamping (when on planet, will be 0 in space)
                }
                CannonComponent {
                    ammo,
                    damage,
                    fireRate,
                    cannonSize,
                    cannonVelocity,
                },
                HealthComponent {
                    maxHealth
                },
                MapComponent {
                    color,
                    distance
                }
            }

            and what about multi entity groups? eg System
            createPlanetarySystem {
                numPlanets = range(0,10),
                distFromBarycenter = range(0, 10),
                distFromNextEntity = range()
            }

            or in theory allow scripting?
            lets not reinvent this wheel.
            stop brain. this is getting ridiculous.

[ ] stats
    [ ] shots fired
    [ ] shots hit
    [ ] distance travelled
    [ ] planets visited

[ ] DEBUG
    [ ] in game console
        /~https://github.com/StrongJoshua/libGDX-inGameConsole
        [ ] show debug output
            redirect all gdx.log calls?
        [ ] commands
            eg: /create entity <ship>
                /add component <component> <entity id>
                /enable/disable system <"system name">
                /setcamfocus <entity>
                /takecontrol <entity> (set control /input focus, if has AI, override (or maybe swap with player would be cool)
                /transfercomponent <component> <entityFrom> <entityTo>
    [x] debug system internals need to go back to old rendering, the new DebugText is horrible on memory.
        i originally did that to make it statically accessible from any system and render properly when called from systems in any priority
        so leave that for external use, just do internals locally
    [...] engine viewer
        [...] arrow navigation and menu expansion
            [x] fix some edge cases on up and down and expansion of empty nodes
            [ ] nothing select, re-select last selected / refocus
            [ ] press and hold up & down
            [ ] page up / down jump to top / bottom
        [ ] aesthetics and usability
            [ ] on key navigation, if selection out of scrollpane view, scroll to make it visible
            [ ] fix arrow expand image on entity node pre/post expand
            [ ] fix scroll bar to show
            [ ] focus on mouse over
        [ ] options
            [ ] poll rate
            [x] toggle history highlighting
            [ ] expand all collapse all
        [...] history (like PE), if added, green for a second. if removed, red for a second
            [ ] systems should get history too, currently only entities working
            [ ] include children
        [x] add count to system and entities node eg: Entities (57), Systems (12)
        [ ] filter for components, bonus points for values (eg: all entities with a health component where component.health > x)
        [ ] possibly a generic reflection object explorer
        [ ] watch window (when node is highlighted, on key or watch button, copy node into its own focused window (including children)
        [ ] field editing
        [ ] add / remove objects
    [ ] FPS,memory,entity graph
        [ ] profiler: /~https://github.com/libgdx/ashley/pull/215

[ ] optimization
    /~https://github.com/libgdx/libgdx/wiki/Profiling
    /~https://github.com/libgdx/libgdx/wiki/Memory-management
    [ ] look at pooled engine/sprites
        [ ] eg bullets. current cannon creates new sprite for each shot. bad!
    [ ] model cache / renderable for 3d sprites
        https://xoppa.github.io/blog/a-simple-card-game/#reduce-the-number-of-render-calls
    [ ] planets are rendered offscreen needlessly -> cull frustum
    [ ] something is funny with the memory, it climbs then resets in a cyclical fashion
        I have a feeling this is a poor use of 'new' somewhere and when the memory resets its the GC cleaning it up
    [ ] fonts should all be in skin, ensure fonts are not duplicated/loaded twice
        https://libgdx.com/wiki/managing-your-assets#writing-your-own-loaders
    http://gameprogrammingpatterns.com/data-locality.html
    http://t-machine.org/index.php/2014/03/08/data-structures-for-entity-systems-contiguous-memory/
    /~https://github.com/junkdog/entity-system-benchmarks#entity-system-benchmarks

[...] investigate possible bug in ashley.
    Found 2 weird cases related to families / listeners.
    I would expect all references to a system/family membership to be when a system is removed from the engine.
    This may be intended behavior and I am using ashley wrong, need to reproduce these in a new project to confirm...
    In the context of this game, both occurrences where triggered when going transitioning between space/world which involves loading and unloading specific systems.
    /~https://github.com/0XDE57/SpaceProject/commit/012bd0bdea4ef5c95b6f8b9454e96a7007d4c7ac
    [A] scenario A:
        1. create engine.
        2. add a new instance of system (SystemA) to engine that subscribes to a family
        3. create a new engine (re-instantiate the original)
        4. add a new instance of system (SystemA) to engine that subscribes to a family.
        5. this new system will not pick up those entities in the family, where it should
        * solution: engine.removeAllEntities(); before re-instantiating engine and system. this resolves the issue.
        Reproduced in ReproFamilyBugTest.class;
    [B] scenario B:
        1. create engine
        2. add a new instance of a system that is an entity listener
        3. remove that system
        4. add a new instance of that system
        5. remove again = crash on System.entityRemoved() when Engine.removeAllEntities():
            Exception in thread "LWJGL Application" java.lang.NullPointerException
            	at com.spaceproject.systems.SpaceLoadingSystem.entityRemoved(SpaceLoadingSystem.java:91)
            	at com.badlogic.ashley.core.FamilyManager.updateFamilyMembership(FamilyManager.java:117)
            	at com.badlogic.ashley.core.Engine.removeEntityInternal(Engine.java:223)
            	at com.badlogic.ashley.core.Engine$EngineEntityListener.entityRemoved(Engine.java:257)
            	at com.badlogic.ashley.core.EntityManager.removeEntityInternal(EntityManager.java:110)
            	at com.badlogic.ashley.core.EntityManager.removeEntity(EntityManager.java:53)
            	at com.badlogic.ashley.core.EntityManager.removeAllEntities(EntityManager.java:72)
            	at com.badlogic.ashley.core.Engine.removeAllEntities(Engine.java:98)
        * Solution: engine.removeEntityListener(the system) when removing system

------------------------------------------OUT_OF_SCOPE---------------------------------------------
[OUT_OF_SCOPE] Planetary Base Building
    Player can spawn on, or land on a  planet. And walk around.
    Give player character tools hammer / pickaxe for mining.
    Ore / minerals / materials will be algorithmically dispersed throughout the planet.
        - rock
        - iron
        - steel
        - silver
        - gold
        - diamonds
        - etc, added as needed
    Player can use materials for building.
    Can also be used for trading at space stations -> sell gold / diamonds for currency -> buy ships / upgrades.
    Player tools: (for now player always has sledge and pickaxe by default, can't drop, can use with click, switch equipped with hotkey)
        sledge hammer   : breaking rock, destruction, attack(hit enemy, do damage, knockback force),
        pickaxe         : mining minerals
        sword           : damage
    I really don't want to do a complex crafting system, keep it simple.
    For now, the only items should be raw materials themselves.
        eg: i dont want to have to build a wall item with rock and steel,
            i should just be able to place a wall if i have the raw materials cost
            i don't want to hold onto a wall item.
    - get rock / ore -> turn into items / entities
        - walls (cost: rock, steel)
            - blocks bullets, takes little to no damage from player
        - landing pad (cost: rock)
            - lays down a gravelly / paved sort of pad, and a places a flag(no cost) (which shows wind direction)
            - when landing on planet, you will land at your home base pad (or last used pad if multiple)
            - use: typically would make this the first step of picking your base location, then build walls around it
        - gates (cost: rock, steel
            - (walls with sliding block)
            - can be manually open closed by player, (box2D sensor)
            - powered component, open close requires power source
        - roads: (cost: rock)
            - gravelly paved path to walk / drive on
            - probably just cosmetic, could perhaps have physics implications for vehicle
        - bridge: to cross river
        - terminal (base computer)
            - I/O cables and circuitry / scripting possibilities...way out of scope.

[OUT_OF_SCOPE] multiplayer
    simple lan arena mode 1v1: one computer hosts, other computer joins
    scope: get physics synced and tweak combat to feel good.
    https://libgdx.com/wiki/networking
    udp vs tcp
    p2p vs server client
    https://www.gabrielgambetta.com/client-server-game-architecture.html
    https://developer.valvesoftware.com/wiki/Source_Multiplayer_Networking


[OUT_OF_SCOPE] "Persistence Engine" what to do with rest of universe when on a planet? or stuff going on on planets when we are in space?
    genericize and make work land and take off work for AI, system doesn't support non-player world switching
    dumb loop where AI lands on planet, kept in some kind of background
    processing state/alt engine, wait a second then take off to test all is working correctly
    background engine meant to be low processing effort (eg: ultra dumbed down AI or simulations, no rendering, no physics, just states and events) to keep track of important entities
    and states between space and worlds. eg: give entity important flag component to keep relevant, if dont have flag dont care and remove when switch
    will be useful for persistence, AI and story type events.
    //Example scenario:
    //    you are on planet, you attack an AI, Ai comes after you. But you leave in your ship.
    //    then AI gets TimedPersistenceComponent and will remain on planet for 5 minutes waiting for you, because angry!
    //    maybe they will come after you. this could be very simple. we can fake intelligence in a background system in persistence engine
    //
    //    Think similar to skyrim, you attack someone in a house and leave they follow you out.
    eg:
    Engine persistenceEngine.
    if (player switch screen) {
        //move important entities from main to background processing
        for each entity in mainEngine {
            if (entity has PersistenceComponent) {
                persistenceEngine.Add(entity);
            }
        }
        //move relevant entity from background processing to main
        for each entity in persistenceEngine {
            if (entity has PersistenceComponent) {
                if (is persistence relevant to new context) {
                    //example relevance:
                    //player in space, important entity on planet
                    //if land on planet with important entity, load into actual engine
                    mainEngine.Add(entity);
                    //could be more nuanced, like perhaps entity is only loaded when event triggers it
                    //or specific location on planet. dunno till start implementing.
                    //possibly have multiple engines handling contexts? (thats dumb and overkill. keep it simple.)
                }
            }
        }
    }
    if (AI switch screen) {
        //similar thing to above
        //if relevant load it, else keep in background

        //if not important, remove from engine, forget about existence
    }



~~~~~~~~~~~~~~~~~~~~RESOURCES!!!~~~~~~~~~~~~~~~~~~~~
/~https://github.com/rafaskb/awesome-libgdx#readme

Controller icons! All of the assets are in the public domain under Creative Commons 0 (CC0)
    https://thoseawesomeguys.com/prompts/
Kenney Assets - High quality assets for your game, from 2D and 3D art to sound effects.
    https://kenney.nl/
OpenGameArt.org - Repository offering a variety of open content assets.
    https://opengameart.org/
Game-Icons.net - Repository containing heaps of cool game related graphics.
    https://game-icons.net/
freesound.org - Huge collaborative database of audio snippets, samples, recordings, bleeps.
    https://freesound.org/
fonts
    http://www.fontsquirrel.com/

https://itch.io/game-assets/free/tag-16-bit

https://opensource.org/faq#profit

Splines
https://www.youtube.com/watch?v=jvPPXbo87ds