SpaceTira

Welcome

SpaceTira is a Galaga-inspired HTML5 canvas space shooter. It runs fully in the browser with no backend or database required. This guide covers first run to production deployment.

Requirements

You need Node.js (LTS) and npm. Use VS Code (recommended) or any editor. For local testing, use Laragon or a static local server.

Quick Start

1. Run npm install once
2. Edit config.json and lang.json
3. Run npm run build
4. Upload the generated out/ folder

The out/ folder is production output. Config and language values are baked into HTML at build time.

VS Code Setup

Download VS Code from code.visualstudio.com. Open the project with File > Open Folder.

You can run build from terminal with npm run build. For local preview, install Live Server and open index.html.

Node.js Setup

Windows

1. Install Node.js LTS from nodejs.org
2. Enable the installer option to add Node to PATH
3. Restart terminal, run node -v and npm -v

macOS

1. Install Node.js LTS from nodejs.org
2. Restart terminal and run which node, node -v, npm -v
3. If needed, add Node path to your shell profile

Laragon Setup (Windows)

1. Install Laragon from laragon.org
2. Create a blank app folder under www
3. Copy SpaceTira project files into that folder
4. Open the local domain, then run npm install and npm run build

Config Guide (config.json)

Primary customization is in config.json. Edit it, run npm run build, then deploy out/. For full keys, see docs/config-reference.md.

game

Core gameplay includes playerSpeed, bulletSpeed, enemyRows, enemyCols, lives, waveDelay, and pauseDebounce.

game.waves

Controls wave cadence with firstWaveEnemyCount, miniBossEvery, and bigBossEvery.

game.progression

Starting progression values: startLevel, startWave, startMultiverse.

game.ai

Motion tuning for smooth formations and dives:

• tickRateHz, maxFrameDeltaMs
• arrival.durationMs, arrival.staggerMs, arrival.lateralJitterPx
• formation.lerp
• attack.warmupMs, attack.targetDriftPx
• visuals.starTwinkleHz, visuals.arrivalPulseHz

game.powerups

Power-up enable/drop configuration is under game.powerups. Example: doubleBarrel supports enabled, dropChance, duration, shape, and color.

game.bosses

Boss durability and attack tuning: miniBoss.hp, miniBoss.specialAttacks, bigBoss.hp, bigBoss.shieldHp, bigBoss.specialAttacks.

colors

Theme keys include brandPrimary, brandDark, bgDark, menuHoverColor, statValueColor, and scrollbar styles under colors.scrollbar.

audio

bgmUrl and bgmVolume control background audio. disableSynthesizedFallback disables generated fallback sounds.

developer

Runtime behavior flags: disabledebugger, consoleWarning, touchControls, autoFullscreenOnMobile.

ui

UI behavior and branding:

• ui.forceHttps, ui.viewport.disableZoom
• ui.loader loader visuals and timeout
• ui.touchControls joystick/action placement
• ui.branding title, subtitle, description banner
• ui.menu button order, labels, icons
• ui.support, ui.credits, ui.docs, ui.shop, ui.footer

seo

Metadata and social cards: siteUrl, title, description, keywords, ogImage, locale, robots, search verifications, and theme colors.

analytics

Google Analytics 4 settings with analytics.enabled and analytics.measurementId.

ads

AdSense settings: enabled, clientId, loadForVerification, plus slot maps for IDs, placeholders, and enabled state.

lang

lang selects which language block from lang.json is used at runtime.

Translations (lang.json)

lang.json stores UI strings. Keep keys, translate values. For additional languages, add another language object and set config.lang to that key.

Gameplay

Move, shoot, survive enemy formations, and clear waves. Every few waves trigger miniboss and boss encounters based on your wave settings. Progression advances through levels and multiverses.

Score Share System

SpaceTira uses static score sharing. No backend required. Score data is encoded into the share URL and rendered by /score. High score is kept in localStorage.

Build

Run npm run build. Output goes to out/. Runtime assets are hashed under out/spacetira/. Deploy only out/.

Deploy

Upload the full out/ folder to any static host (Cloudflare Pages, Netlify, Vercel, cPanel, GitHub Pages).

Cloudflare: Direct Upload

1. Run npm run build
2. Deploy out/ using Pages dashboard or Wrangler
3. If Wrangler is configured, you can use npm run deploy

Cloudflare: GitHub

1. Connect your repo in Cloudflare Pages
2. Build command: npm run build
3. Output directory: out

Netlify / Vercel / cPanel

Use build command npm run build and publish directory out, or upload out/ manually.

Troubleshooting

Build fails or node not found

Install Node.js LTS and confirm node -v, npm -v work in a new terminal.

Config changes not visible

Config is baked at build time. Run npm run build after edits, then redeploy out/.

Game does not load

Check browser console and ensure all files under out/spacetira/ were uploaded.

Score page not opening

Use the built route /score (or /score/) and ensure host serves score/index.html.

Touch controls not showing

Set developer.touchControls to true to force display, or keep "auto" for mobile/small screens.

Project Structure

spacetira-proj/
|-- index.html                 - main game page
|-- 404.html                   - fallback page
|-- config.json                - settings and branding
|-- lang.json                  - translations
|-- build.js                   - build script
|-- package.json               - npm scripts/dependencies
|-- assets/
|   |-- styles/style.css       - UI styles
|   |-- js/                    - runtime modules
|   |-- bgm/                   - background music
|   |-- icons/                 - support/shop/social icons
|   |-- docs.html              - docs modal content
|   |-- about.html             - about modal content
|   |-- terms.html             - terms modal content
|   |-- privacy.html           - privacy modal content
|   `-- fonts/                 - game fonts
|-- docs/
|   |-- user-guide.html        - buyer quick guide
|   |-- config-reference.md    - config keys
|   |-- docs.md                - technical docs
|   `-- docs-page-template.html - full docs page template
|-- score/
|   `-- index.html             - score share page
`-- out/                       - production build output

Support

Discord: natadtech.com/join/discord
Telegram: t.me/NatadTech