Alpha Force CLI

English · 中文 · Download · Screenshots

English

Alpha Force CLI is a terminal tactical shooter built with Go and Bubble Tea. It supports offline Solo Mode and LAN Online Room Mode, using a semi-real-time fixed-tick top-down PvPvE ruleset: movement, shooting, reloading, AI, and win/loss resolution are all advanced by the core simulation.

The project is currently a playable prototype with a complete Solo Mode match flow and a two-player LAN room flow.

At a Glance

Item	Description
Genre	Terminal top-down tactical shooter
Main modes	Solo Mode, LAN Online Room Mode
Multiplayer model	Host-authoritative; clients only send input
Recommended download	GitHub Releases

Screenshots

Main menu:

Solo Mode match:

Screenshots are generated from real TUI render output. To refresh them, run:

go run -buildvcs=false ./scripts/render_readme_screenshots.go

Features

• Solo Mode: play locally on a preset map against Computer Opponents.
• Online Room Mode: the Host creates a LAN room; clients only send input while the Host runs authoritative simulation and broadcasts snapshots.
• Semi-real-time fixed tick: matches keep advancing without turn confirmation.
• Basic Rifle: 25 damage, 8 rounds, 0.4 second cooldown, 1.5 second reload.
• Tactical items: picked-up Smoke Grenades and Medkits fill slots 1-5; press the matching number to use them, and full inventory blocks more pickups.
• Multiple Computer Opponent types: aggressive, flanking, defensive, and cautious AI types use different decision preferences and pacing.
• Lightweight Cover AI: Computer Opponents search for Half Cover, shoot, reload, reposition, and are affected by smoke line-of-sight blockers.
• Tactical map HUD: shows walls, half cover, smoke, pickups, players, AI, bullet trails, event logs, and end-of-match results.
• Local settings: saves nickname, default port, mouse input preference, and interface language.

Requirements

• Go 1.24.2 or newer.
• A terminal with ANSI color support.
• Terminal size at least 100x32; the app prompts you to resize if the window is too small.
• For LAN play, the Host port must be reachable on the local network. The default port is 7777.

Download

If you do not want to build locally, download a packaged build from GitHub Releases. Open the latest Release and choose the file for your system:

• macOS: download the .tar.gz archive, extract it, and run alpha-force.
• Windows: download the .zip archive, extract it, and run alpha-force.exe.

If the Releases page does not have downloadable files yet, use the Quick Start commands below to run from source.

Quick Start

Run directly:

go run -buildvcs=false ./cmd/alpha-force

Build a local binary:

go build -buildvcs=false -o bin/alpha-force ./cmd/alpha-force
./bin/alpha-force

If your repository is a normal Git checkout, you can omit -buildvcs=false.

Controls

Action	Key
Move	W A S D
Rotate aim direction	Q / E
Fire	Space or F
Reload	R
Use item	1-5
Return to main menu / leave room	Esc
Quit	Ctrl+C

Solo Mode

1. Start the app.
2. Select Solo Mode.
3. During the opening countdown, confirm your ▲ marker and enemy ☠ positions.
4. Use movement, aiming, firing, and reloading to eliminate all Computer Opponents.

Win condition: the local Player eliminates all Computer Opponents. Loss condition: the local Player is eliminated.

LAN Online Room Mode

Two Local Terminals

Open two terminals.

Terminal A:

go run -buildvcs=false ./cmd/alpha-force

Select Create Room. The default listening port is 7777.

Terminal B:

go run -buildvcs=false ./cmd/alpha-force

Select Join Room, enter 127.0.0.1 as the Host IP, and enter the port shown by the Host. Return to Terminal A and press Enter or S in the Lobby to start the match.

Multiple Machines on LAN

After the Host selects Create Room, share the displayed LAN IPv4 address and port with the other players. Joining players select Join Room and enter the Host LAN IP and port.

If joining the room fails, check:

• Whether the Host and clients are on the same LAN.
• Whether the Host port is blocked by a firewall or security software.
• Whether the entered Host IP and port match the Lobby display.
• Whether the match has already started; the current version does not support joining an in-progress match.

Configuration

Local settings are saved under the operating system user config directory at AlphaForce/settings.json. Configurable items include:

• Nickname
• Default Port
• Mouse Input
• Language

Default project values are defined in internal/config/defaults.yaml and embedded into the binary at build time.

Development

Common commands:

gofmt -w ./cmd ./internal
go test ./...

For changes involving core simulation, AI, LAN, or TUI behavior, also consider running:

go test -race ./internal/game ./internal/ai ./internal/lan ./internal/tui
go vet ./...

Project structure:

Path	Purpose
cmd/alpha-force	Executable entry point
internal/app	App startup and top-level orchestration
internal/config	Local settings and default config
internal/game	Map, movement, combat, win/loss resolution, and snapshots
internal/ai	Computer Opponent Cover AI
internal/lan	LAN host/client protocol, Lobby, and snapshot broadcast
internal/tui	Bubble Tea model, input, menus, HUD, and map rendering
docs/verification	Automated acceptance and manual verification checklists

Release Packaging

Generate release archives under release/:

./scripts/package.sh mac 0.1.0
./scripts/package.sh win 0.1.0
./scripts/package.sh all 0.1.0

By default, macOS builds produce .tar.gz archives for darwin/arm64 and darwin/amd64, and Windows builds produce a .zip archive for windows/amd64. Use RELEASE_ARCHES=amd64 to limit a build to one architecture.

License

Alpha Force CLI is released under the MIT License.

中文

Alpha Force CLI 是一款使用 Go 和 Bubble Tea 构建的终端战术射击游戏。它支持离线 Solo Mode 和局域网 Online Room Mode，采用半实时固定 tick 的上帝视角 PvPvE 规则：移动、射击、装弹、AI 和胜负结算都由核心模拟统一推进。

当前项目处于可玩原型阶段，已覆盖一局完整 Solo Mode 和双人 LAN 房间流程。

项目概览

项目	说明
游戏类型	终端上帝视角战术射击
主要模式	Solo Mode、LAN Online Room Mode
联机规则	Host-authoritative，客户端只发送输入
推荐下载	GitHub Releases

截图

主菜单：

Solo Mode 对局：

截图由真实 TUI 渲染输出生成。需要刷新截图时运行：

go run -buildvcs=false ./scripts/render_readme_screenshots.go

功能

• Solo Mode：本地玩家进入预设地图，对抗 Computer Opponents。
• Online Room Mode：Host 创建 LAN 房间，客户端只发送输入，Host 负责权威模拟和 snapshot 广播。
• 半实时固定 tick：对局持续推进，不依赖回合确认。
• Basic Rifle：25 damage、8 rounds、0.4 秒冷却、1.5 秒装弹。
• 战术道具：拾取烟雾弹和急救包后进入 1-5 栏位，按数字键使用；栏位已满时不能继续拾取。
• 多类型 Computer Opponent：突击、绕侧、守点、谨慎等 AI 类型拥有不同决策偏好和行动节奏。
• 轻量 Cover AI：Computer Opponents 会寻找 Half Cover、射击、装弹、重新定位，并受烟雾视线阻断影响。
• 战术地图 HUD：显示墙体、半掩体、烟雾、物资、玩家、AI、射击轨迹、事件日志和战后结算。
• 本地设置：保存昵称、默认端口、鼠标输入偏好和界面语言。

运行要求

• Go 1.24.2 或更新版本。
• 支持 ANSI 色彩的终端。
• 终端窗口至少 100x32；尺寸不足时应用会提示调整。
• LAN 联机时 Host 端口需要在局域网内可访问，默认端口为 7777。

下载

不想本地构建的话，可以到 GitHub Releases 下载已经打包好的版本。进入最新 Release 后，按自己的系统选择对应文件：

• macOS：下载 .tar.gz 包，解压后运行 alpha-force。
• Windows：下载 .zip 包，解压后运行 alpha-force.exe。

如果 Releases 页面暂时没有可用文件，可以先按下面的快速开始命令从源码运行。

快速开始

直接运行：

go run -buildvcs=false ./cmd/alpha-force

构建本地二进制：

go build -buildvcs=false -o bin/alpha-force ./cmd/alpha-force
./bin/alpha-force

如果你的仓库是正常 Git checkout，也可以去掉 -buildvcs=false。

操作

动作	按键
移动	W A S D
旋转瞄准方向	Q / E
开火	Space 或 F
装弹	R
使用道具	1-5
返回主菜单 / 离开房间	Esc
退出	Ctrl+C

Solo Mode

1. 启动应用。
2. 选择 Solo Mode。
3. 在开场倒计时中确认自己的 ▲ 标识和敌方 ☠ 位置。
4. 使用移动、瞄准、开火和装弹操作淘汰所有 Computer Opponents。

胜利条件：本地 Player 淘汰所有 Computer Opponents。失败条件：本地 Player 被淘汰。

LAN Online Room Mode

同一台机器双开测试

打开两个终端。

终端 A：

go run -buildvcs=false ./cmd/alpha-force

选择 Create Room，默认监听端口为 7777。

终端 B：

go run -buildvcs=false ./cmd/alpha-force

选择 Join Room，Host IP 输入 127.0.0.1，端口输入 Host 显示的端口。回到终端 A，在 Lobby 中按 Enter 或 S 开始对局。

局域网多机联机

Host 选择 Create Room 后，把界面显示的局域网 IPv4 和端口发给其他玩家。加入者选择 Join Room，输入 Host 的 LAN IP 和端口。

如果无法加入房间，请检查：

• Host 和客户端是否在同一局域网内。
• Host 端口是否被防火墙或安全软件拦截。
• 输入的 Host IP 和端口是否与 Lobby 显示一致。
• 对局是否已经开始；当前版本不支持中途加入正在进行的对局。

配置

本地设置会保存到操作系统用户配置目录下的 AlphaForce/settings.json。可配置项包括：

• Nickname
• Default Port
• Mouse Input
• Language

项目默认值定义在 internal/config/defaults.yaml，构建时会嵌入二进制。

开发

常用命令：

gofmt -w ./cmd ./internal
go test ./...

涉及核心模拟、AI、LAN 或 TUI 行为时，建议追加：

go test -race ./internal/game ./internal/ai ./internal/lan ./internal/tui
go vet ./...

项目结构：

路径	职责
cmd/alpha-force	可执行入口
internal/app	应用启动和顶层编排
internal/config	本地设置和默认配置
internal/game	地图、移动、战斗、胜负和 snapshot
internal/ai	Computer Opponent Cover AI
internal/lan	LAN host/client 协议、Lobby 和 snapshot 广播
internal/tui	Bubble Tea 模型、输入、菜单、HUD 和地图渲染
docs/verification	自动化验收和手动验收清单

发布打包

生成发布归档到 release/：

./scripts/package.sh mac 0.1.0
./scripts/package.sh win 0.1.0
./scripts/package.sh all 0.1.0

macOS 默认生成 darwin/arm64 和 darwin/amd64 的 .tar.gz，Windows 默认生成 windows/amd64 的 .zip。可以用 RELEASE_ARCHES=amd64 限制单次构建架构。

许可证

Alpha Force CLI 使用 MIT License 开源。