Lua Game Example - Space Shooter

A visually appealing space shooter game built with Lua and the LOVE2D framework, demonstrating procedural graphics, particle effects, and game state management.

Table of Contents

• Quick Start
• Prerequisites
• Installation
• Running the Game
• Game Controls
• Project Structure
• TypeScript/JavaScript Integration
• Extending the Game

---

Quick Start

Step 1: Install Dependencies

For learners, use the automated installation script:

macOS/Linux:

./install.sh

Windows:

install.bat

The script will guide you through installing all required dependencies.

Step 2: Start the Project

Launch the game and/or integration examples:

macOS/Linux:

./start.sh

Windows:

start.bat

The start script provides an interactive menu to:

• Run the LOVE2D game (frontend)
• Run JavaScript integration examples (backend)
• Run TypeScript integration examples (backend)
• Run game with backend services
• Run all services simultaneously

---

Prerequisites

Installing LOVE2D

macOS (Homebrew):

brew install love

macOS (Manual):

1. Download from https://love2d.org/
2. Move LOVE.app to Applications folder
3. Add to PATH: alias love="/Applications/love.app/Contents/MacOS/love"

Windows:

1. Download installer from https://love2d.org/
2. Run installer
3. LOVE2D will be available in your PATH

Linux (Ubuntu/Debian):

sudo apt install love

Linux (Arch):

sudo pacman -S love

---

Installation

# Clone or download this project
cd lua-example

# Verify LOVE2D installation
love --version

---

Running the Game

Option 1: Using the start script (Recommended)

# macOS/Linux
./start.sh

# Windows
start.bat

Option 2: Manual start

# From the project directory
love .

# Or specify the full path
love /path/to/lua-example

---

Game Controls

Key	Action
W / Up Arrow	Move up
S / Down Arrow	Move down
A / Left Arrow	Move left
D / Right Arrow	Move right
Space	Shoot / Start game

---

Project Structure

lua-example/
├── install.sh        # Automated setup script (macOS/Linux)
├── install.bat       # Automated setup script (Windows)
├── start.sh          # Start script with menu (macOS/Linux)
├── start.bat         # Start script with menu (Windows)
├── main.lua          # Main game logic (WITH SPRITE SUPPORT)
├── conf.lua          # LOVE2D configuration
├── IMPLEMENTED_SPRITES.md  # How your sprites are integrated
├── YOUR_SPRITES.md         # Quick sprite reference
├── assets/           # Game assets (images, sounds, fonts)
│   └── README.txt    # Asset loading guide
├── logs/             # Backend service logs
├── README.md         # This file
└── integration/      # TypeScript/JavaScript examples
    ├── lua-bridge.ts
    ├── lua-runner.js
    ├── tstl-game.ts
    ├── package.json
    ├── tsconfig.json
    ├── tsconfig.tstl.json
    └── types/        # TypeScript type declarations
        ├── fengari.d.ts
        ├── fengari-interop.d.ts
        └── README.md

Sprites Integrated

The game now uses custom sprites:

• 4 player ship variations
• 23 enemy ship types
• 11 background images

See YOUR_SPRITES.md for quick reference or IMPLEMENTED_SPRITES.md for full details.

---

TypeScript/JavaScript Integration

There are several ways to integrate Lua with TypeScript/JavaScript:

Option 1: Fengari (Lua VM in JavaScript)

Fengari is a Lua 5.3 implementation in JavaScript that runs in browsers and Node.js.

cd integration
npm install
npm run example

Option 2: TypeScriptToLua

Transpile TypeScript directly to Lua code for use in LOVE2D.

npm install -g typescript-to-lua
tstl --project tsconfig.json

Option 3: Electron + LOVE2D

Bundle LOVE2D with Electron for desktop distribution with web technologies.

Option 4: Wasmoon (WebAssembly Lua)

High-performance Lua 5.4 via WebAssembly.

npm install wasmoon

See the integration/ folder for complete examples.

---

Extending the Game

Adding Graphical Images

The game currently uses procedural graphics (shapes drawn with code), but you can easily add sprite images for the spaceship, bullets, and enemies.

See ADDING_IMAGES.md for a complete step-by-step guide on:

• Where to place image files
• How to load images in Lua
• How to modify the game to use sprites
• Where to find free game assets
• Example code with image fallbacks

Quick example:

-- In love.load()
local spaceship = love.graphics.newImage("assets/spaceship.png")

-- In love.draw()
love.graphics.draw(spaceship, x, y)

A ready-to-use version with image support is available in main-with-images.lua.

Adding New Enemy Types

In main.lua, modify the spawnEnemy() function:

local enemyTypes = {
    -- Add new enemy type
    {
        width = 80,
        height = 40,
        speed = 50,
        color = {0.2, 0.8, 0.2},
        health = 5,
        points = 500
    }
}

Adding Power-ups

1. Create a powerups table
2. Add spawn logic in love.update
3. Check collision with player
4. Apply effects (speed boost, multi-shot, shield)

Adding Sound Effects

-- In love.load()
local sounds = {
    shoot = love.audio.newSource("assets/shoot.ogg", "static"),
    explosion = love.audio.newSource("assets/explosion.ogg", "static")
}

-- When shooting
sounds.shoot:clone():play()

Adding Background Music

-- In love.load()
local music = love.audio.newSource("assets/music.ogg", "stream")
music:setLooping(true)
music:play()

---

Graphics Techniques Used

1. Glow Effects: Multiple semi-transparent layers drawn at increasing sizes
2. Particle Systems: Explosion particles with velocity, decay, and color
3. Parallax Scrolling: Stars at different speeds for depth perception
4. Procedural Shapes: Ships and enemies drawn with polygons, not sprites
5. Color Theming: Consistent color schemes for visual cohesion

---

Performance Tips

• Use love.graphics.newCanvas() for pre-rendering static elements
• Batch similar draw calls together
• Use sprite sheets instead of individual images
• Pool objects instead of creating/destroying frequently
• Use love.graphics.SpriteBatch for many similar sprites

---

Resources

• LOVE2D Documentation
• LOVE2D Forums
• Lua 5.1 Reference Manual
• Awesome LOVE2D
• TypeScriptToLua
• Fengari

---

License

MIT License - Feel free to use this code for any purpose.