docsReading time: 3 minutes

General

Basics

Advanced

Tutorials

Performance Optimization

LITIENGINE is designed to be efficient, but game performance depends on how you use it. This guide covers common optimization techniques.

Measuring Performance

Enable Debug Metrics

// Show FPS and tick rate
Game.config().debug().setShowGameMetrics(true);

Or in config.properties:

cl_showGameMetrics=true

Custom Metrics

long startTime = System.nanoTime();

// Code to measure

long elapsed = System.nanoTime() - startTime;
System.out.println("Operation took: " + (elapsed / 1_000_000.0) + "ms");

Rendering Optimization

Reduce Draw Calls

Every render call has overhead. Batch similar operations:

// BAD: Multiple state changes
for (Entity e : entities) {
  g.setColor(e.getColor());
  g.fill(e.getBoundingBox());
}

// GOOD: Batch by color
Map<Color, List<Entity>> byColor = groupByColor(entities);
for (Map.Entry<Color, List<Entity>> entry : byColor.entrySet()) {
  g.setColor(entry.getKey());
  for (Entity e : entry.getValue()) {
    g.fill(e.getBoundingBox());
  }
}

Limit Visible Entities

Only render what’s on screen:

@Override
public void render(Graphics2D g) {
  Rectangle2D viewport = Game.world().camera().getViewport();

  for (IEntity entity : entities) {
    if (viewport.intersects(entity.getBoundingBox())) {
      // Only render visible entities
      entity.render(g);
    }
  }
}

Use Static Lighting

Pre-bake shadows instead of calculating dynamically:

gfx_enableDynamicShadows=false

See Static Lighting for details.

Entity Management

Suspend Inactive Entities

Disable updates for off-screen entities:

// In custom entity
@Override
public void update() {
  if (!isOnScreen()) {
    return; // Skip update
  }
  // Normal update logic
}

Object Pooling

Reuse objects instead of creating new ones:

public class BulletPool {
  private static final List<Bullet> pool = new ArrayList<>();

  public static Bullet get() {
    if (pool.isEmpty()) {
      return new Bullet();
    }
    return pool.remove(pool.size() - 1);
  }

  public static void release(Bullet bullet) {
    bullet.reset();
    pool.add(bullet);
  }
}

Limit Entity Count

// Remove entities when not needed
if (Game.world().environment().getEntities().size() > MAX_ENTITIES) {
  // Remove oldest/distant entities
}

Particle System

Limit Particle Count

emitter.getData().setMaxParticles(50);  // Set reasonable limit

Suspend Off-Screen Emitters

emitter.setSuspended(!isOnScreen());

Use Simple Particles

Shapes are faster than animated sprites:

emitter.getData().setParticleType(ParticleType.SQUARE);

Memory Management

Unload Unused Resources

// Clear unused spritesheets
Resources.spritesheets().clear();

// Remove disposed entities
entity.dispose();

Avoid Memory Leaks

// Remove listeners when disposing
public void dispose() {
  Game.loop().detach(this);
  Input.keyboard().removeKeyListener(listener);
}

Use Primitive Collections

For large collections, use primitive arrays:

// Consider using int[] instead of List<Integer> for large datasets

Physics Optimization

Limit Collision Checks

// Use appropriate collision types
@CollisionInfo(collisionType = Collision.STATIC)  // For walls
@CollisionInfo(collisionType = Collision.DYNAMIC) // For moving entities

Use Simple Collision Shapes

Rectangles are faster than complex polygons:

// Prefer simple collision boxes
collisionEntity.setCollisionBoxWidth(32);
collisionEntity.setCollisionBoxHeight(32);

Configuration

Frame Rate Settings

# Limit FPS to reduce CPU usage
cl_maxFps=60

# Enable V-Sync
gfx_vsync=true

Resolution Scaling

# Reduce internal resolution
gfx_enableResolutionScale=true

Profiling Tips

Profile before optimizing: Measure to find actual bottlenecks
Test on target hardware: Low-end systems show issues first
Check GC logs: Frequent garbage collection indicates memory issues
Use Java VisualVM: Connect to running game for detailed profiling

Common Performance Issues

Issue	Symptom	Solution
Too many entities	Low FPS	Limit count, use pooling
Large spritesheets	Memory spike	Reduce image sizes
Excessive particles	Frame drops	Lower particle count
Complex collision	Stuttering	Simplify shapes
Memory leaks	Gradual slowdown	Dispose resources properly