ForgeTactic

A portrait pixel-art AFK blacksmith management game for mobile, built in Godot 4.3.

ForgeTactic is an offline vertical slice: hire smiths, queue weapon crafts that finish while the app is closed, send parties on material adventures, and expand a warm forge shop from wood-tier gear toward mystical relics. Progress persists locally; no online account or PVP is required.

---

What the vertical slice includes

System	Behavior
Forge queue	Wall-clock craft jobs with offline completion on load
Economy	Quality-based gold pricing with smooth tier curves
Roster	Hire and train smiths; stats blend into crafted weapons
Research	Unlock additional weapon types over time
Traits & rarity	Quality bands, deterministic traits, rarity-scaled sell value
Smith training	Per-stat training with scaling gold costs
World map	Six tier-aligned zones with level/prestige gates
Adventure	Seeded expeditions for materials; failures are soft
Prestige	Late-game reset that gates the Mystical tier
Save	Local user://forgetactic_save.cfg with pause/quit flush

Shared rules and tunables live in docs/CONTRACT.md.

v0.2 features

• Traits and rarity — Crafted weapons roll a deterministic trait and a rarity band from quality (Common through Mythic). Display names, trait descriptions, and sell prices reflect rarity.
• Blueprints — Locked weapon types unlock through gold plus wood-tier materials and a short research timer, reachable from starter resources.
• Smith training — Each smith exposes train actions for speed, quality, magic, and strength with costs that scale with the current stat.
• World map — Six adventure zones from Wooded Marches through Mystical Rift, each gated by shop level (Mystical also requires prestige).
• Art pass — Cleaner pixel weapons, material icons, zone map markers, and rarity frame overlays at a consistent scale.

v0.3.1 — NavBar was clipped off 1080p desktops

Root cause: viewport was 720×1280 with stretch/scale_mode=integer, which refuses to shrink. On a typical 1080p monitor the window is ~1008px tall, so the entire bottom NavBar (Forge / Smiths / Blueprints / Map / More) was off-screen — exactly the "zero bottom tabs" report. Mouse mapping was also broken.

Fix: fractional stretch + DisplayFit so the window always fits the usable screen while keeping aspect. Hub input filters restored so panels receive clicks. Craft button now disables when mats/queue are insufficient. FTUE economy tuned (start gold 80, adventure threshold 0.65, cheaper first blueprint).

---

v0.3 features

• Rebuilt Hub shell — Title and Hub are exclusive sibling screens (no overlay host). The Hub is a VBoxContainer of TopBar / Content / NavBar, so the five bottom tabs (Forge · Smiths · Blueprints · Map · More) can never fall off-screen or be masked by a leftover full-rect layer.
• BugSink error reporting — A pure-GDScript Sentry-envelope client (src/core/BugSink.gd, autoloaded) reports a boot event, a rolling breadcrumb trail (tab switches), and explicit error captures to BugSink project 8. Works on desktop and Android; disabled in headless CI. Override with SENTRY_DSN.
• Layout gate tests — GUT asserts the NavBar is visible and tall enough, that exactly five labelled tabs exist, and that each tab reveals its panel.

---

Architecture

The project separates engine-free logic from presentation so the rule set runs headless in CI.

src/core/     Pure game logic (no scene/UI dependencies)
  FTConfig.gd        Tunables, tier enums, economy math helpers
  FTRng.gd           Seeded RNG for adventures
  Blacksmith.gd      Smith stats and appearance seed
  WeaponItem.gd      Crafted weapon data and gold_value()
  CraftQueue.gd      Timed jobs with offline resolve
  Roster.gd          Hire/train and average stats
  Research.gd        Weapon-type unlocks
  AdventureSystem.gd Dispatch and claim for materials
  ShopState.gd       Gold, mats, inventory, level, prestige
  Game.gd            Autoload save/load singleton

src/game/     Presentation (hub UI, pixel art, touch targets)
  Main.tscn / Main.gd   Forge hub and bottom navigation

test/unit/    GUT acceptance tests (define the Logic lane bar)
scripts/      CI helpers, local run, economy simulation probe
Jenkinsfile   Primary CI pipeline (mirrors Aphelion layout)

Pixel art uses nearest-neighbor filtering and a warm forge palette documented in the contract. Touch targets are at least 48px with one primary call-to-action per panel.

---

Running the game

Requires Godot 4.3 (standard, non-Mono).

# Detached launch with import + log capture:
bash scripts/run_local.sh

# Or open the project directly:
godot --path . res://src/game/Main.tscn

Portrait layout targets 720×1280 with canvas stretch and mobile orientation. Desktop window overrides provide a comfortable preview size.

---

Testing

Tests use GUT (vendored under addons/gut/).

# Full headless suite (same as Jenkins Unit Tests stage):
bash scripts/ci_test.sh

# Economy monotonicity probe:
godot --headless -s scripts/sim_economy.gd

Unit tests cover economy curves, craft queue offline resolve, weapon stat blend, adventure determinism, prestige gates, save round-trips, FTUE craft→sell flow, and UI compatibility (Main/Hub scenes, HubHost input safety). They reference the contract class names (FTConfig, WeaponItem, CraftQueue, ShopState, etc.) and gate merges until Logic implements matching APIs.

Portrait UI rules (integer scale, nearest pixel art, touch targets, input safety) live in docs/UI_STANDARDS.md.

---

Continuous Integration (Jenkins)

Primary CI runs on Jenkins (same pattern as Aphelion). Create or update the job with:

bash scripts/setup_jenkins_job.sh

Pipeline stages:

1. Project Readiness — scripts/ci/check_project.sh verifies required files.
2. Setup Godot — pinned headless Godot 4.3 into a workspace cache.
3. Unit Tests — GUT suite with JUnit report (test_results.xml). Hard gate.
4. Economy Simulation — headless monotonic gold probe (scripts/sim_economy.gd).
5. Export Linux / Export Android APK — artifacts forgetactic.x86_64 and forgetactic.apk under build/. Export may mark the build unstable if SDK templates are missing on the agent.
6. Publish Release — when enabled and an APK exists, attaches assets to the Forgejo release for ./VERSION (scripts/ci_publish_release.sh).

Repository: epistemophiliac/forge-tactic-godot on Forgejo. Version tag source: ./VERSION (currently 0.3.1). To remove a mistaken release before re-publishing, run scripts/ci_replace_release.sh (requires FORGEJO_USER / FORGEJO_TOKEN).

A lightweight GitHub Actions mirror (.github/workflows/production-readiness.yml) runs the same static readiness check for forks that do not use Jenkins.

---

Dependencies and licensing

• Godot Engine 4.3 — MIT
• GUT (Godot Unit Test) — MIT, vendored in addons/gut/

Game code and design in this repository are original works for the ForgeTactic vertical slice.