Skip to content

Getting Started

Jump to bottom
joshuaaferguson edited this page Jun 17, 2026 · 3 revisions

Getting Started with Terminal Velocity

Welcome, pilot! This guide will help you get Terminal Velocity up and running and teach you the basics of gameplay.

Table of Contents

Installation

Quick Start (Docker - Recommended)

The easiest way to get started is with Docker:

# Clone repository
git clone https://github.com/JoshuaAFerguson/terminal-velocity.git
cd terminal-velocity

# Configure environment
cp .env.example .env
# Edit .env and set DB_PASSWORD

# Start the stack
docker compose up -d

# Connect to game
ssh -p 2222 username@localhost

Manual Installation

Prerequisites

  • Go 1.24+ - Install Go (see go.mod for the exact required version)
  • PostgreSQL 14+ - Required for persistent state; the game needs a database to run
  • Git - For cloning the repository
  • Make - For using Makefile commands (optional, you can go build directly)

Step 1: Install Go

On Ubuntu/Debian:

wget https://go.dev/dl/go1.23.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc

On macOS (with Homebrew):

brew install go

Verify installation:

go version

Step 2: Clone Repository

git clone https://github.com/JoshuaAFerguson/terminal-velocity.git
cd terminal-velocity

Step 3: Install Dependencies

go mod download

Step 4: Set Up Database (Optional)

For full features, set up PostgreSQL:

# Install PostgreSQL
sudo apt update && sudo apt install postgresql postgresql-contrib

# Create database
sudo -u postgres psql
CREATE DATABASE terminal_velocity;
CREATE USER terminal_velocity WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE terminal_velocity TO terminal_velocity;
\q

# Initialize schema
psql -U postgres -d terminal_velocity -f scripts/schema.sql

Step 5: Configure Server

cp configs/config.example.yaml configs/config.yaml
# Edit configs/config.yaml with your settings

Key configuration options:

server:
  port: 2222              # SSH port
  max_players: 100        # Max concurrent players

game:
  starting_credits: 10000 # Starting money
  num_systems: 100        # Universe size
  enable_pvp: true        # Enable player combat

database:
  host: "localhost"
  port: 5432
  user: "terminal_velocity"
  database: "terminal_velocity"
  # Leave `password` unset and supply DB_PASSWORD via env for better hygiene.

Env vars DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_SSLMODE are honored as fallbacks for any field you leave out of the YAML.

Step 6: Run Server

# Using Make
make run

# Or directly
go run cmd/server/main.go

The server will start on port 2222.

Connecting to a Server

Using SSH Client

Connect to any Terminal Velocity server using SSH:

ssh -p 2222 any-user@server-address

The SSH-layer username is not used for authentication — the server accepts any SSH identity and prompts for your game username and password inside the TUI's login screen. Using your real game username in the ssh command is a nice convention but not required.

Examples:

# Local server
ssh -p 2222 tester@localhost

# Remote server
ssh -p 2222 tester@game.example.com

First Connection

When connecting for the first time:

  1. The login screen appears
  2. Tab to Create New Account to register (available when the server's AllowRegistration is enabled)
  3. Or type your username, Tab, type your password, Tab to Login, Enter

First Time Setup

Account Registration

When you first connect, you'll go through the registration process:

  1. Welcome Screen: Shows game information and options
  2. Username: Choose a unique username (3-20 characters)
  3. Password: Set a secure password (minimum 8 characters)
  4. Email (optional): For account recovery
  5. Starting System: Choose your starting location

Tips for registration:

  • Choose a memorable username (you can't change it later)
  • Use a strong password
  • Starting system doesn't matter much - you can travel anywhere

Interactive Tutorial

After registration, you'll be guided through an interactive tutorial covering:

  1. Basic Navigation - Moving around the UI
  2. Trading Fundamentals - Your first trade
  3. Ship Management - Understanding your ship
  4. Combat Basics - How to fight
  5. Mission System - Accepting missions
  6. Multiplayer Features - Chat and social
  7. Advanced Features - Settings, quests, events

You can skip the tutorial anytime, but we recommend completing it for the best experience.

Basic Controls

Navigation

Terminal Velocity uses keyboard navigation:

Key Action
Arrow Keys Navigate menus
Enter Select/Confirm
Esc Go back/Cancel
Tab Switch between sections
? Help (context-sensitive)
q Quit current screen

Main Menu Options

After logging in, you'll see the main menu with these options:

  1. Navigation - Travel between star systems
  2. Market - Buy and sell commodities
  3. Shipyard - Purchase and upgrade ships
  4. Outfitter - Install weapons and equipment
  5. Missions - Accept and track missions
  6. Quests - View active quests and storylines
  7. Events - Participate in server-wide events
  8. Chat - Multiplayer communication
  9. Faction - Player faction management
  10. Stats - View your statistics and achievements
  11. Settings - Configure preferences
  12. Help - In-game help system
  13. Logout - Exit the game

Common Commands

While playing:

  • /help - Show help
  • /chat [message] - Send global chat
  • /whisper [player] [message] - Private message
  • /status - Show your status
  • /location - Show your current location

Your First Steps

Step 1: Explore the Main Menu

Take a moment to explore the main menu. Press Enter on different options to see what they do. Don't worry - you can always go back with Esc.

Step 2: Check Your Ship

Select Ship Info from the main menu to see your starting ship:

Your Starting Ship:

  • Type: Shuttle
  • Value: 25,000 credits
  • Cargo Space: 20 units
  • Hull: 100 HP
  • Shields: 50 HP
  • Fuel: 100 units

Starting Credits: 10,000 credits

This is enough to start trading!

Step 3: Make Your First Trade

Let's make some money! See our detailed Trading Guide for strategies, but here's a quick start:

  1. Go to Market - Select "Market" from main menu
  2. Check Prices - Look for cheap commodities (Food, Water, Textiles)
  3. Buy Cargo - Purchase what you can afford (leave room for profit!)
  4. Navigate to Another System - Select "Navigation" from main menu
  5. Jump to High-Tech System - Look for tech level 6+ systems
  6. Sell Cargo - Go to Market and sell for profit!

Example First Trade:

  • Buy 20 units of Food at 50 cr/unit = 1,000 cr
  • Travel to high-tech system (500 cr fuel cost)
  • Sell Food at 100 cr/unit = 2,000 cr
  • Profit: 500 cr (50% ROI)

Step 4: Upgrade Your Ship

After a few successful trades:

  1. Save up 50,000 credits
  2. Visit the Shipyard
  3. Upgrade to a Courier (40 cargo space)
  4. Trade-in your Shuttle for 70% value discount
  5. Now you can haul more cargo = more profit!

Step 5: Try Combat (Optional)

When you're ready for action:

  1. Accept a combat mission from the Mission Board
  2. Navigate to the target system
  3. Engage the enemy
  4. Use turn-based tactical combat
  5. Collect loot and bounties!

See the Combat Guide for detailed tactics.

Step 6: Join the Community

Terminal Velocity is multiplayer! Connect with other players:

  1. Open Chat menu
  2. Say hello in global chat
  3. Join or create a Faction
  4. Participate in Dynamic Events
  5. Trade with other players
  6. Compete on Leaderboards

Next Steps

Now that you're set up, explore these guides:

Essential Guides

Advanced Topics

Reference

Quick Tips for New Players

Economy Tips

  • Start small: Don't invest all your credits in one trade
  • Tech level matters: High-tech systems pay more for low-tech goods
  • Leave fuel money: Always keep 500-1000 cr for fuel
  • Diversify: Don't rely on one commodity

Combat Tips

  • Start easy: Accept Easy difficulty missions first
  • Upgrade weapons: Visit Outfitter before major combat
  • Use tactics: Position matters in turn-based combat
  • Retreat option: You can always run away if outmatched

Progression Tips

  • Follow quests: Main quests teach mechanics and give rewards
  • Join events: Dynamic events give bonus rewards
  • Join a faction: Multiplayer factions provide support
  • Track achievements: Achievements give direction and rewards

Social Tips

  • Be friendly: The community is helpful
  • Ask questions: Use global chat for help
  • Join a faction: Team play is more fun
  • Trade fairly: Build a good reputation

Troubleshooting

Can't Connect

  • Check port: Server runs on port 2222 by default
  • Check firewall: Ensure port 2222 is open
  • Check server status: Is the server running?

Game Crashed

  • Auto-save: Game auto-saves every 30 seconds
  • Reconnect: Just reconnect - your progress is saved
  • Report bugs: Use GitHub Issues

Performance Issues

  • Terminal size: The TUI adapts to the connected terminal via SSH pty-req / window-change events. 80×24 is the hard minimum; 120×40 or bigger is recommended — several screens were designed for wider layouts and will truncate long rows at 80 cols. The UI also re-renders live when you resize your terminal mid-session.
  • SSH quality: Poor connection may cause lag
  • Server load: High player count may slow server

For more help, see Troubleshooting or ask in the community!

Getting Help

In-Game Help

  • Press ? for context-sensitive help
  • Select Help from main menu
  • Use tutorial system (can be restarted anytime)

Community Help

Documentation

Welcome aboard, Commander! The galaxy awaits! 🚀

Next: Gameplay Guide - Learn the core mechanics

Terminal Velocity Wiki

Home

Getting Started

Gameplay Guides

Technical Docs

Server Admin

Reference

Version: 0.7.0 Status: Feature Complete

Clone this wiki locally