Make codex write some javadoc that I'm too lazy to do :P

13 files changed, 228 insertions, 7 deletions

diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/AbstractionEngineGame.java b/core/src/main/java/coffee/liz/abstractionengine/app/AbstractionEngineGame.java
index b54776f..9d07220 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/AbstractionEngineGame.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/AbstractionEngineGame.java
@@ -21,6 +21,9 @@ public class AbstractionEngineGame extends Game {
 	public FitViewport viewport;
 	public ShapeRenderer shapeRenderer;
 
+	/**
+	 * Game initialization hook.
+	 */
 	public void create() {
 		viewport = new FitViewport(WORLD_SIZE.getX(), WORLD_SIZE.getY());
 		batch = new SpriteBatch();
@@ -32,10 +35,16 @@ public class AbstractionEngineGame extends Game {
 		viewport.update(Gdx.graphics.getWidth(), Gdx.graphics.getHeight(), true);
 	}
 
+	/**
+	 * Game render hook.
+	 */
 	public void render() {
 		super.render();
 	}
 
+	/**
+	 * Game cleanup hook.
+	 */
 	public void dispose() {
 		batch.dispose();
 		font.dispose();
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/actor/BlockyButton.java b/core/src/main/java/coffee/liz/abstractionengine/app/actor/Button.java
index df2c749..a7416b9 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/actor/BlockyButton.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/actor/Button.java
@@ -16,7 +16,7 @@ import lombok.RequiredArgsConstructor;
 import lombok.Setter;
 
 @RequiredArgsConstructor
-public class BlockyButton extends Actor {
+public class Button extends Actor {
 	private static final float ALPHA = 0.85f;
 	private static final float BORDER_WIDTH = 1f;
 
@@ -36,6 +36,14 @@ public class BlockyButton extends Actor {
 	private final Color bgColor = new Color();
 	private final Color borderColor = new Color();
 
+	/**
+	 * Actor draw hook.
+	 *
+	 * @param batch
+	 *            parent batch
+	 * @param parentAlpha
+	 *            parent alpha multiplier
+	 */
 	@Override
 	public void draw(final Batch batch, final float parentAlpha) {
 		batch.end();
@@ -80,6 +88,9 @@ public class BlockyButton extends Actor {
 		}
 	}
 
+	/**
+	 * Enables input handling for the button.
+	 */
 	public void addButtonListener() {
 		addListener(new InputListener() {
 			@Override
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/actor/LifeGridActor.java b/core/src/main/java/coffee/liz/abstractionengine/app/actor/LifeGridActor.java
index 6692413..43b83a5 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/actor/LifeGridActor.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/actor/LifeGridActor.java
@@ -37,6 +37,12 @@ public class LifeGridActor extends Actor {
 	@Setter
 	private Vec2<Float> parallaxOffset = Vec2f.ZERO;
 
+	/**
+	 * Actor update hook.
+	 *
+	 * @param delta
+	 *            time since last frame
+	 */
 	@Override
 	public void act(final float delta) {
 		super.act(delta);
@@ -48,6 +54,14 @@ public class LifeGridActor extends Actor {
 		world.update(new LifeInput(forcedAlive), Duration.ofMillis((int) (delta * 1000)));
 	}
 
+	/**
+	 * Actor draw hook.
+	 *
+	 * @param batch
+	 *            parent batch
+	 * @param parentAlpha
+	 *            parent alpha multiplier
+	 */
 	@Override
 	public void draw(final Batch batch, final float parentAlpha) {
 		if (viewport == null) {
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/actor/Logo.java b/core/src/main/java/coffee/liz/abstractionengine/app/actor/Logo.java
index 41847b5..e8bf025 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/actor/Logo.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/actor/Logo.java
@@ -10,11 +10,22 @@ import com.badlogic.gdx.utils.Disposable;
 public class Logo extends Actor implements Disposable {
 	private final Texture texture;
 
+	/**
+	 * Creates a logo actor.
+	 */
 	public Logo() {
 		this.texture = new Texture(Gdx.files.internal("sprites/logo.png"));
 		setSize(texture.getWidth(), texture.getHeight());
 	}
 
+	/**
+	 * Actor draw hook.
+	 *
+	 * @param batch
+	 *            parent batch
+	 * @param parentAlpha
+	 *            parent alpha multiplier
+	 */
 	@Override
 	public void draw(final Batch batch, final float parentAlpha) {
 		final Color c = getColor();
@@ -22,6 +33,9 @@ public class Logo extends Actor implements Disposable {
 		batch.draw(texture, getX(), getY(), getWidth(), getHeight());
 	}
 
+	/**
+	 * Releases actor resources.
+	 */
 	@Override
 	public void dispose() {
 		texture.dispose();
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/actor/Penguin.java b/core/src/main/java/coffee/liz/abstractionengine/app/actor/Penguin.java
index 09b3d5b..4a557e7 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/actor/Penguin.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/actor/Penguin.java
@@ -25,6 +25,9 @@ public class Penguin extends Actor implements Disposable {
 	private Animation<TextureRegion> currentAnimation;
 	private float stateTime = 0f;
 
+	/**
+	 * Creates a penguin actor.
+	 */
 	public Penguin() {
 		this.texture = new Texture(Gdx.files.internal("sprites/penguins.png"));
 		final TextureRegion[][] tmp = TextureRegion.split(texture, texture.getWidth() / PENGUIN_FRAMES.getX(),
@@ -48,12 +51,26 @@ public class Penguin extends Actor implements Disposable {
 		this.currentAnimation = tobaganning;
 	}
 
+	/**
+	 * Actor update hook.
+	 *
+	 * @param delta
+	 *            time since last frame
+	 */
 	@Override
 	public void act(final float delta) {
 		super.act(delta);
 		stateTime += delta;
 	}
 
+	/**
+	 * Actor draw hook.
+	 *
+	 * @param batch
+	 *            parent batch
+	 * @param parentAlpha
+	 *            parent alpha multiplier
+	 */
 	@Override
 	public void draw(final Batch batch, final float parentAlpha) {
 		final TextureRegion frame = currentAnimation.getKeyFrame(stateTime, true);
@@ -62,6 +79,12 @@ public class Penguin extends Actor implements Disposable {
 		batch.draw(frame, getX(), getY(), getWidth(), getHeight());
 	}
 
+	/**
+	 * Sets the current animation state.
+	 *
+	 * @param state
+	 *            new state
+	 */
 	public void setState(final State state) {
 		this.currentAnimation = switch (state) {
 			case EEPY -> eepy;
@@ -70,6 +93,9 @@ public class Penguin extends Actor implements Disposable {
 		};
 	}
 
+	/**
+	 * Releases actor resources.
+	 */
 	@Override
 	public void dispose() {
 		texture.dispose();
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/life/CellState.java b/core/src/main/java/coffee/liz/abstractionengine/app/life/CellState.java
index f25ad7c..025cde0 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/life/CellState.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/life/CellState.java
@@ -12,10 +12,21 @@ public class CellState implements Component {
 
 	private final float alivePercentage;
 
+	/**
+	 * Creates a cell state with a normalized alive percentage.
+	 *
+	 * @param alivePercentage
+	 *            alive value in the range [0, 1]
+	 */
 	public CellState(final float alivePercentage) {
 		this.alivePercentage = clamp(alivePercentage);
 	}
 
+	/**
+	 * Returns true when the cell is considered alive.
+	 *
+	 * @return whether the cell is alive
+	 */
 	public boolean isAlive() {
 		return alivePercentage >= (1.0f - EPS);
 	}
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/life/LifeSystem.java b/core/src/main/java/coffee/liz/abstractionengine/app/life/LifeSystem.java
index 82aa9c6..14c783f 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/life/LifeSystem.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/life/LifeSystem.java
@@ -20,10 +20,26 @@ public class LifeSystem extends BaseGridIndexSystem<LifeInput> {
 
 	private Duration sinceUpdate = Duration.ZERO;
 
+	/**
+	 * Creates a life system.
+	 *
+	 * @param dimensions
+	 *            grid size
+	 */
 	public LifeSystem(final Vec2<Integer> dimensions) {
 		super(dimensions);
 	}
 
+	/**
+	 * Advances the simulation.
+	 *
+	 * @param world
+	 *            world to update
+	 * @param state
+	 *            input state for this tick
+	 * @param dt
+	 *            time step
+	 */
 	@Override
 	public void update(final World<LifeInput> world, final LifeInput state, final Duration dt) {
 		super.update(world, state, dt);
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/screen/GameScreen.java b/core/src/main/java/coffee/liz/abstractionengine/app/screen/GameScreen.java
index adaad0e..c3fe2c8 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/screen/GameScreen.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/screen/GameScreen.java
@@ -8,36 +8,65 @@ import lombok.RequiredArgsConstructor;
 public class GameScreen implements Screen {
 	private final AbstractionEngineGame game;
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void show() {
 
 	}
 
+	/**
+	 * Screen render hook.
+	 *
+	 * @param delta
+	 *            time since last frame
+	 */
 	@Override
 	public void render(float delta) {
 
 	}
 
+	/**
+	 * Screen resize hook.
+	 *
+	 * @param width
+	 *            new width in pixels
+	 * @param height
+	 *            new height in pixels
+	 */
 	@Override
 	public void resize(int width, int height) {
 
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void pause() {
 
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void resume() {
 
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void hide() {
 
 	}
 
+	/**
+	 * Screen cleanup hook.
+	 */
 	@Override
 	public void dispose() {
 
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/screen/MainMenu.java b/core/src/main/java/coffee/liz/abstractionengine/app/screen/MainMenu.java
index f1b6b02..06d0b03 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/screen/MainMenu.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/screen/MainMenu.java
@@ -2,7 +2,7 @@ package coffee.liz.abstractionengine.app.screen;
 
 import coffee.liz.abstractionengine.app.AbstractionEngineGame;
 import coffee.liz.abstractionengine.app.Theme;
-import coffee.liz.abstractionengine.app.actor.BlockyButton;
+import coffee.liz.abstractionengine.app.actor.Button;
 import coffee.liz.abstractionengine.app.actor.LifeGridActor;
 import coffee.liz.abstractionengine.app.screen.mainmenu.MainMenuAudio;
 import coffee.liz.abstractionengine.app.life.CellState;
@@ -44,6 +44,9 @@ public class MainMenu implements Screen {
 	private LifeGridActor lifeGridActor;
 	private MainMenuAudio audioSystem;
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void show() {
 		Mat2.init(GRID_DIMENSIONS, pos -> world.createEntity().add(new GridPosition(pos))
@@ -68,13 +71,13 @@ public class MainMenu implements Screen {
 		final float centerX = (worldWidth - BUTTON_WIDTH) / 2f;
 		final float startY = worldHeight / 2f + BUTTON_HEIGHT;
 
-		final BlockyButton playButton = createButton("Play", centerX, startY);
+		final Button playButton = createButton("play", centerX, startY);
 		playButton.setOnClick(() -> game.setScreen(new GameScreen(game)));
 		stage.addActor(playButton);
 	}
 
-	private BlockyButton createButton(final String text, final float x, final float y) {
-		final BlockyButton button = new BlockyButton(game.shapeRenderer, game.font, text);
+	private Button createButton(final String text, final float x, final float y) {
+		final Button button = new Button(game.shapeRenderer, game.font, text);
 		button.setPosition(x, y);
 		button.setSize(BUTTON_WIDTH, BUTTON_HEIGHT);
 		button.addButtonListener();
@@ -94,6 +97,12 @@ public class MainMenu implements Screen {
 		return gliderPattern;
 	}
 
+	/**
+	 * Screen render hook.
+	 *
+	 * @param delta
+	 *            time since last frame
+	 */
 	@Override
 	public void render(final float delta) {
 		game.viewport.apply();
@@ -116,24 +125,44 @@ public class MainMenu implements Screen {
 		lifeGridActor.setParallaxOffset(parallax);
 	}
 
+	/**
+	 * Screen resize hook.
+	 *
+	 * @param width
+	 *            new width in pixels
+	 * @param height
+	 *            new height in pixels
+	 */
 	@Override
 	public void resize(final int width, final int height) {
 		game.viewport.update(width, height, true);
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void pause() {
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void resume() {
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void hide() {
 		dispose();
 	}
 
+	/**
+	 * Screen cleanup hook.
+	 */
 	@Override
 	public void dispose() {
 		audioSystem.dispose();
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/screen/ScrollLogo.java b/core/src/main/java/coffee/liz/abstractionengine/app/screen/ScrollLogo.java
index 225457f..ab2aa5e 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/screen/ScrollLogo.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/screen/ScrollLogo.java
@@ -30,6 +30,9 @@ public class ScrollLogo implements Screen {
 	private Penguin penguin;
 	private Group animationGroup;
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void show() {
 		stage = new Stage(game.viewport, game.batch);
@@ -73,6 +76,12 @@ public class ScrollLogo implements Screen {
 						Actions.fadeOut(fadeDuration), Actions.run(this::requestTransition)));
 	}
 
+	/**
+	 * Screen render hook.
+	 *
+	 * @param delta
+	 *            time since last frame
+	 */
 	@Override
 	public void render(final float delta) {
 		game.viewport.apply();
@@ -81,24 +90,44 @@ public class ScrollLogo implements Screen {
 		stage.draw();
 	}
 
+	/**
+	 * Screen resize hook.
+	 *
+	 * @param width
+	 *            new width in pixels
+	 * @param height
+	 *            new height in pixels
+	 */
 	@Override
 	public void resize(final int width, final int height) {
 		game.viewport.update(width, height, true);
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void pause() {
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void resume() {
 	}
 
+	/**
+	 * Screen lifecycle hook.
+	 */
 	@Override
 	public void hide() {
 		dispose();
 	}
 
+	/**
+	 * Screen cleanup hook.
+	 */
 	@Override
 	public void dispose() {
 		if (logo != null) {
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/screen/mainmenu/MainMenuAudio.java b/core/src/main/java/coffee/liz/abstractionengine/app/screen/mainmenu/MainMenuAudio.java
index 516fded..bb8beda 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/screen/mainmenu/MainMenuAudio.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/screen/mainmenu/MainMenuAudio.java
@@ -77,12 +77,21 @@ public class MainMenuAudio implements Runnable, Disposable {
 	@Getter
 	private Thread audioThread;
 
+	/**
+	 * Creates a main menu audio controller.
+	 *
+	 * @param gridDimensions
+	 *            grid size used for scaling activity
+	 */
 	public MainMenuAudio(final Vec2<Integer> gridDimensions) {
 		this.device = Gdx.audio.newAudioDevice(SAMPLE_RATE, true);
 		this.gridDimensions = gridDimensions;
 		this.maxActivity = gridDimensions.getX() * gridDimensions.getY() * MAX_ACTIVITY_FRACTION;
 	}
 
+	/**
+	 * Starts the background audio thread.
+	 */
 	public void start() {
 		audioThread = new Thread(this, "main-menu-audio");
 		audioThread.setDaemon(true);
@@ -90,8 +99,10 @@ public class MainMenuAudio implements Runnable, Disposable {
 	}
 
 	/**
-	 * Updates activity metrics derived from current grid entities. This drives
-	 * chord density and positional tones in the audio thread.
+	 * Updates the audio inputs from current entities.
+	 *
+	 * @param entities
+	 *            grid entities to sample
 	 */
 	public void update(final Collection<Entity> entities) {
 		float totalActivity = 0.0f;
@@ -121,6 +132,9 @@ public class MainMenuAudio implements Runnable, Disposable {
 		}
 	}
 
+	/**
+	 * Audio thread loop.
+	 */
 	@Override
 	public void run() {
 		while (running) {
@@ -197,6 +211,9 @@ public class MainMenuAudio implements Runnable, Disposable {
 				+ (float) Math.sin(positionYPhase * TWO_PI) * positionVolume * POSITION_Y_GAIN;
 	}
 
+	/**
+	 * Releases audio resources.
+	 */
 	@Override
 	public void dispose() {
 		running = false;
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/utils/FunctionUtils.java b/core/src/main/java/coffee/liz/abstractionengine/app/utils/FunctionUtils.java
index 32f2dc1..8304977 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/utils/FunctionUtils.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/utils/FunctionUtils.java
@@ -4,6 +4,12 @@ public final class FunctionUtils {
 	private FunctionUtils() {
 	}
 
+	/**
+	 * Runs the provided action and wraps failures.
+	 *
+	 * @param run
+	 *            action to execute
+	 */
 	public static <E extends Throwable> void runUninterrupted(final ThrowableRunnable<E> run) {
 		try {
 			run.run();
@@ -14,6 +20,9 @@ public final class FunctionUtils {
 
 	@FunctionalInterface
 	public interface ThrowableRunnable<E extends Throwable> {
+		/**
+		 * Performs the action.
+		 */
 		void run() throws E;
 	}
 }
diff --git a/core/src/main/java/coffee/liz/abstractionengine/app/utils/TimerUtils.java b/core/src/main/java/coffee/liz/abstractionengine/app/utils/TimerUtils.java
index d411ddc..dea7bd2 100644
--- a/core/src/main/java/coffee/liz/abstractionengine/app/utils/TimerUtils.java
+++ b/core/src/main/java/coffee/liz/abstractionengine/app/utils/TimerUtils.java
@@ -6,6 +6,13 @@ public final class TimerUtils {
 	private TimerUtils() {
 	}
 
+	/**
+	 * Creates a {@link Timer.Task} from a runnable.
+	 *
+	 * @param r
+	 *            action to run
+	 * @return timer task that runs the action
+	 */
 	public static Timer.Task sideEffectTask(final Runnable r) {
 		return new Timer.Task() {
 			@Override