0 Fork 0

Files

T

fez5587 9318e5dd2d feat: Add initial SpaceTrader project files, forms, resources, and image assets.

2025-11-19 12:25:17 -05:00

30 KiB

Raw Permalink Blame History

Reference Implementation Notes

This document provides detailed analysis of the two complete Space Trader implementations included in this repository for study and reference.

Overview

The source/ directory contains two complete, working implementations of Space Trader:

space-trader/ - Java/Android mobile port by Russell Wolf
SpaceTraderSource201/ - C#/.NET Windows desktop version by Jay French

Both are based on the original Palm OS game by Pieter Spronck (2002) and implement the full game mechanics.

1. Java/Android Implementation

Location: source/space-trader/

Project Details

Author: Russell Wolf (based on original by Pieter Spronck)
Platform: Android mobile application
Version: 1.3.5 (versionCode 23)
License: GPL v3+
Contact: spacetrader@brucelet.com
Repository: Originally at bitbucket.org/brucelet/space-trader

Build System

Gradle-based Android project for Android Studio 1.5.0+

Configuration:

compileSdkVersion: 23
minSdkVersion: 8 (Android 2.2 Froyo)
targetSdkVersion: 23 (Android 6.0 Marshmallow)
Application ID: com.brucelet.spacetrader
Dependencies: AppCompat v7 (23.2.1)

Build Commands:

cd source/space-trader

# Debug build
./gradlew assembleDebug
# Output: app/build/outputs/apk/debug/app-debug.apk

# Release build (requires signing)
./gradlew assembleRelease
# Output: app/build/outputs/apk/release/app-release.apk

# Install to connected device
./gradlew installDebug

Architecture

File Organization: 92 Java source files

Package structure:

com.brucelet.spacetrader/
├── (root) ..................... 48 files - Activities, Screens, Dialogs
├── datatypes/ ................. 5 files - Core game entities
├── enumtypes/ ................. 30 files - Enumerations and constants
└── widget/ .................... 5 files - Custom UI components

Key Components

Main Entry Points:

MainActivity.java - Application entry point, fragment host
Application.java - Custom application class, initialization
DocumentationActivity.java - In-game help system

Core Game State:

datatypes/GameState.java - Singleton managing all game state (~2000+ lines)
- Universe generation
- Game logic and calculations
- Encounter management
- Trading and economy
- Quest tracking
- Save/load functionality

Data Models (datatypes/):

Ship.java - Ship entity with equipment, cargo, stats
SolarSystem.java - Star system with attributes, location
CrewMember.java - Crew/mercenary with skills
HighScore.java - High score records
GameState.java - Central game controller

Enumerations (enumtypes/): 30 enum files defining:

ShipType.java - 10 ship types with specifications
TradeItem.java - 10 trade commodities
Weapon.java - 6 weapon types
Shield.java - 3 shield types
Gadget.java - 7 gadget types
TechLevel.java - 8 technology levels
Politics.java - 7 political systems
SpecialEvent.java - Quest and event triggers
Encounter.java - Encounter types
Difficulty.java, Reputation.java, PoliceRecord.java, etc.

UI Screens (extends BaseScreen):

WarpScreen.java - Warp/travel interface
ChartScreen.java - Galaxy map
EncounterScreen.java - Combat and encounters
BuyScreen.java / SellScreen.java - Cargo trading
BuyShipScreen.java - Shipyard
BuyEqScreen.java / SellEqScreen.java - Equipment
BankScreen.java - Banking/loans
PersonnelScreen.java - Crew management
StatusScreen.java / StatusShipScreen.java / StatusCargoScreen.java - Status views
YardScreen.java - Ship maintenance

Dialogs (extends BaseDialog):

NewGameDialog.java - Character creation
OptionsDialog.java - Game settings
ConfirmDialog.java - Generic confirmation
InputDialog.java - Text input
CheatDialog.java - Debug/cheat menu
HighScoresDialog.java - Score display
And many more...

Custom Widgets:

FixedRatioImageView.java - Aspect-ratio preserving images
ShortcutButton.java - Quick action buttons
MenuDropDownWindow.java - Custom menus
EncounterHelpActionProvider.java - Context help

Android-Specific Features

Resources:

Multi-DPI drawables (ldpi, mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi)
RTL (right-to-left) layout support
XML layouts for all screens
Animations (anim/ and anim-v11/)
Color resources
String resources (localization-ready)

Manifest Features:

Portrait orientation lock
Backup agent for cloud save
Install location: auto (internal/external storage)
No special permissions required

Lifecycle Management:

Proper Activity lifecycle handling
State preservation across configuration changes
Background task management with AsyncTask

Code Patterns

Singleton Pattern:

// GameState.java uses singleton
private static GameState instance;
public static GameState getInstance() { ... }

Listener Pattern:

public interface OnConfirmListener {
    void onConfirm();
}

Screen Navigation:

// Fragment-based screen transitions
public void showScreen(ScreenType screenType) { ... }

2. C#/.NET Windows Implementation

Location: source/SpaceTraderSource201/

Project Details

Author: Jay French
Additional Coding: David Pierron
Original Authors: Pieter Spronck, Sam Anderson, Samuel Goldstein, Matt Lee
Platform: Windows Desktop (.NET Framework 3.5)
Version: 2.00
License: GPL v2+
Contact: spacetrader@frenchfryz.com
Website: spacetraderwin.sourceforge.net

Build System

Visual Studio 2008 solution targeting .NET Framework 3.5

Configuration:

Solution: SpaceTrader.sln
Project: Fryz.Apps.SpaceTrader.csproj
Output Type: Windows Forms Application (WinExe)
Assembly Name: SpaceTrader.exe
Namespace: Fryz.Apps.SpaceTrader

Dependencies:

System.dll
System.Data.dll
System.Drawing.dll
System.Windows.Forms.dll
System.Xml.dll

Build Commands:

# Using MSBuild (requires .NET Framework 3.5 SDK)
msbuild Fryz.Apps.SpaceTrader.csproj /p:Configuration=Debug
msbuild Fryz.Apps.SpaceTrader.csproj /p:Configuration=Release

# Using Visual Studio
# Open SpaceTrader.sln in Visual Studio
# Build -> Build Solution (F6)

# Output location
# bin/Debug/SpaceTrader.exe
# bin/Release/SpaceTrader.exe

Architecture

File Organization: 54 C# source files

Categories:

Core Game Logic ................ 15 files
Form Classes ................... 26 files
Equipment Classes .............. 4 files
Supporting Classes ............. 9 files

Key Components

Entry Point:

SpaceTrader class (in one of the form files) - Main() method

Central Controller:

Game.cs - Massive central game controller (~4000 lines, 148KB)
- Singleton pattern: Game.CurrentGame
- Universe generation
- All game mechanics and calculations
- Encounter system
- Trading and economy
- Quest management
- Save/load via serialization
- Event handling

Main UI:

Form_SpaceTrader.cs - Main game window
- Tabbed interface
- Real-time updates
- Menu system
- Status displays

Dialog Forms (26 total):

Form_NewCommander.cs - Character creation
Form_Options.cs - Settings
Form_Encounter.cs - Combat screen
Form_Shipyard.cs - Buy/sell ships
Form_Equipment.cs - Buy/sell equipment
Form_CargoBuy.cs / Form_CargoSell.cs - Trading
Form_BuyFuel.cs / Form_BuyRepairs.cs - Maintenance
Form_GetLoan.cs / Form_PayBackLoan.cs - Banking
Form_ViewCommander.cs - Character stats
Form_ViewShip.cs - Ship details
Form_ViewBank.cs - Financial status
Form_ViewPersonnel.cs - Crew info
Form_ViewQuests.cs - Quest log
Form_ViewHighScores.cs - Scores
Form_Alert.cs - Message dialogs
Form_Find.cs - System finder
Form_Jettison.cs - Cargo jettison
Form_Plunder.cs - Looting
Form_Monster.cs - Space monster encounter
Form_ShipList.cs - Ship comparison
Form_Costs.cs - Trip cost calculator
Form_About.cs - About dialog
Form_Test.cs - Debug features

Core Data Classes:

Commander.cs - Player character
- Stats: Pilot, Fighter, Trader, Engineer (0-10 each)
- Cash, debt, credits
- Current ship reference
- Police record, reputation
- Insurance, no-claim status
- Kill counts, days played
Ship.cs - Ship entity
- Type, name, equipment slots
- Hull strength, fuel, cargo
- Weapon/shield/gadget arrays
- Crew members
- Image handling
StarSystem.cs - Solar system
- Name, coordinates (x, y)
- Tech level (0-7)
- Political system (Anarchy → Democracy)
- Special resources
- Size, visited flag
- Price multipliers
CrewMember.cs - Mercenary stats
- Skills (Pilot, Fighter, Trader, Engineer)
- Current system location
Shipyard.cs - Ship construction
- Available ships per system
- Special ship handling

Equipment Classes:

Equipment.cs - Base class for all equipment
Weapon.cs - Weapon specifications
Shield.cs - Shield specifications
Gadget.cs - Gadget specifications

Enumerations:

Enums.cs - All game enumerations in one file:
- ShipType (10 types)
- EquipmentType, WeaponType, ShieldType, GadgetType
- TechLevel (0-7)
- PoliticalSystemType (7 types)
- SpecialResource (12 types)
- TradeItemType (10 commodities)
- EncounterType
- Difficulty, Size, Activity
- And 30+ more enums

Constants:

Consts.cs - All game constants (~700 lines):
- Galaxy dimensions: 154 x 110
- Distance constants (MinDistance: 7, MaxRange: 20, WormDist: 25)
- Economic constants (BountyModifier, InsRate, IntRate)
- Skill system (MaxSkill: 10, SkillBonus: 3)
- Ship constants (MaxFuelTanks: 20, MaxSlots: 5)
- Price arrays for all items
- Tech level requirements
- String constants for UI

Utilities:

Functions.cs - Helper functions
- Random number generation
- Distance calculations
- String formatting
- Math utilities
Strings.cs - String constants (~4000 lines)
- All game text
- System names (120+ systems)
- Crew member names
- Dialog text
- Quest descriptions
STSerializableObject.cs - Serialization framework
- Base class for saveable objects
- Hashtable-based serialization
- Version tracking

Supporting Classes:

HighScoreRecord.cs - Score entry
PoliceRecord.cs - Law enforcement status
Reputation.cs - Fame level
PoliticalSystem.cs - Government info
TradeItem.cs - Commodity data
ShipSpec.cs - Ship specifications
ShipTemplate.cs - Ship templates
SpecialEvent.cs - Quest/event data
GameOptions.cs - Settings
GameEndException.cs - Game-ending conditions
FutureVersionException.cs - Save file version check

Resources

Images (images/ directory):

Ship sprites - 4 states per ship (normal, damaged, shield, shield+damaged):
- ship0.bmp through ship10.bmp (player ships)
- mantis.bmp (special ship)
- scarab.bmp (special ship)
- scorp.bmp (special ship)
- Each with variations: *d (damaged), *s (shielded), *sd (shielded+damaged)
Encounter images:
- alien.bmp, pirate.bmp, police.bmp, trader.bmp, special.bmp
Equipment icons:
- w_pulse.bmp, w_beam.bmp, w_military.bmp, w_photon.bmp, w_quantum.bmp, w_morgan.bmp
- s_energy.bmp, s_reflective.bmp, s_lightning.bmp
- g_bays.bmp, g_fuel.bmp, g_cloak.bmp, g_navsys.bmp, g_targsys.bmp, g_repsys.bmp, g_hbays.bmp
Shipyard logos:
- sy-corellian.bmp, sy-incom.bmp, sy-kuat.bmp, sy-sienar.bmp, sy-sorosuub.bmp
UI elements:
- Chart navigation arrows (arrup.bmp, arrdown.bmp, etc.)
- Chart markers (chartlv.bmp, chartsnv.bmp, etc.)
- Tribble stages (trib0.bmp through trib7.bmp)
- Miscellaneous (moon.bmp, bottle.bmp, df.bmp, destroyed.bmp, etc.)

Embedded Resources:

Each Form has a .resx file with embedded resources
Images loaded as embedded resources
Fonts and colors defined in resources

Game Systems Deep Dive

Universe Generation

Galaxy Structure:

Coordinate system: 154 x 110 grid
120+ named star systems procedurally placed
Minimum distance between systems: 7 units
Systems within 13 units considered "close"
Maximum warp range: 20 parsecs (with max fuel)
6 wormholes connecting distant systems (25+ parsecs)

System Attributes:

Tech Level (0-7): Pre-Agricultural → Hi-Tech
Political System (7 types):
- Anarchy (0)
- Capitalist (1)
- Communist (2)
- Confederacy (3)
- Corporate (4)
- Cybernetic (5)
- Democracy (6)
- Dictatorship (7)
- Fascist (8)
- Feudal (9)
- Military (10)
- Monarchy (11)
- Pacifist (12)
- Socialist (13)
- Satori (14)
- Technocracy (15)
- Theocracy (16)
Size (0-4): Tiny → Huge
Special Resources (12 types):
- Nothing, Mineral Rich, Mineral Poor, Desert, Lots of Water,
- Rich Soil, Poor Soil, Rich Fauna, Lifeless, Weird Mushrooms,
- Lots of Herbs, Artistic, Warlike

Placement Algorithm:

Generate random coordinates for each system
Check minimum distance from all existing systems
Reject and regenerate if too close
Assign random attributes (tech, politics, size, resources)
Continue until all systems placed
Generate wormhole pairs
Place special events (quests)
Place shipyards (tech level requirements)

Ship Types

10 Ship Types (in order of size):

Flea (Default starting ship)
- Cargo: 10, Weapons: 0, Shields: 0, Gadgets: 0
- Fuel: 20, Hull: 25, Crew: 1
- Cost: 2,000 credits
- Can convert to Escape Pod
Gnat
- Cargo: 15, Weapons: 1, Shields: 0, Gadgets: 1
- Fuel: 14, Hull: 100, Crew: 1
- Cost: 10,000 credits
Firefly
- Cargo: 20, Weapons: 1, Shields: 1, Gadgets: 1
- Fuel: 17, Hull: 100, Crew: 1
- Cost: 25,000 credits
Mosquito
- Cargo: 15, Weapons: 2, Shields: 1, Gadgets: 1
- Fuel: 13, Hull: 100, Crew: 1
- Cost: 30,000 credits
Bumblebee
- Cargo: 25, Weapons: 1, Shields: 2, Gadgets: 2
- Fuel: 15, Hull: 100, Crew: 2
- Cost: 60,000 credits
Beetle
- Cargo: 50, Weapons: 0, Shields: 1, Gadgets: 1
- Fuel: 14, Hull: 50, Crew: 3
- Cost: 80,000 credits
Hornet
- Cargo: 20, Weapons: 3, Shields: 2, Gadgets: 1
- Fuel: 16, Hull: 150, Crew: 2
- Cost: 100,000 credits
Grasshopper
- Cargo: 30, Weapons: 2, Shields: 2, Gadgets: 3
- Fuel: 15, Hull: 150, Crew: 3
- Cost: 150,000 credits
Termite (Best cargo hauler)
- Cargo: 60, Weapons: 1, Shields: 3, Gadgets: 2
- Fuel: 13, Hull: 200, Crew: 3
- Cost: 225,000 credits
Wasp (Best combat ship)
- Cargo: 35, Weapons: 3, Shields: 2, Gadgets: 2
- Fuel: 14, Hull: 200, Crew: 3
- Cost: 300,000 credits

Special Ships:

Dragonfly - Quest reward ship
Scarab - Quest encounter ship
Scorpion - Dangerous quest ship
Space Monster - Legendary creature (not player-obtainable)

Equipment System

Weapons (6 types):

Pulse Laser (Tech 5) - 2,000 credits - Power: 15
Beam Laser (Tech 6) - 12,500 credits - Power: 25
Military Laser (Tech 7) - 35,000 credits - Power: 35
Photon Disruptor (Quest reward) - Power: 20
Quantum Disruptor (Quest reward) - Power: 30
Morgan's Laser (Special) - Power: 85

Shields (3 types):

Energy Shield (Tech 5) - 5,000 credits - Power: 100
Reflective Shield (Tech 6) - 20,000 credits - Power: 200
Lightning Shield (Tech 7) - 45,000 credits - Power: 350

Gadgets (7 types):

Extra Cargo Bays (5 bays) (Tech 4) - 2,500 credits
Auto-Repair System (Tech 5) - 7,500 credits
Navigation System (Tech 6) - 15,000 credits
Targeting System (Tech 6) - 25,000 credits
Cloaking Device (Tech 7) - 100,000 credits
Fuel Compactor (+3 fuel tanks) (Tech 7) - 30,000 credits
Hidden Cargo Bays (5 bays) (Special) - Cannot be detected

Trade Commodities

10 Commodities with dynamic pricing:

Water
- Base price: 30 credits
- Tech Production: 0 (Pre-Agricultural)
- Tech Usage: 0
- Tech Top Production: 2
- Price increase: Drought (+30%)
- Price decrease: Lots of Water resource
Furs
- Base: 250, Tech Prod: 0, Usage: 0, Top: 0
- Increase: Cold (+10%)
- Decrease: Rich Fauna
Food
- Base: 100, Tech Prod: 1, Usage: 0, Top: 1
- Increase: Crop Failure (+10%), War (+5%)
- Decrease: Rich Soil
Ore
- Base: 350, Tech Prod: 2, Usage: 2, Top: 3
- Increase: War (+10%)
- Decrease: Mineral Rich
Games
- Base: 250, Tech Prod: 3, Usage: 1, Top: 6
- Increase: Boredom (+20%)
- Decrease: Artistic
Firearms
- Base: 1,250, Tech Prod: 3, Usage: 1, Top: 5
- Increase: War (+30%)
- Illegal in some systems
Medicine
- Base: 650, Tech Prod: 4, Usage: 1, Top: 6
- Increase: Plague (+20%)
- Decrease: Lots of Herbs
Machines
- Base: 900, Tech Prod: 4, Usage: 3, Top: 5
- Increase: Lack of Workers (+10%)
Narcotics
- Base: 3,500, Tech Prod: 5, Usage: 0, Top: 5
- Increase: Boredom (+50%)
- Decrease: Weird Mushrooms
- Illegal in most systems
Robots
- Base: 5,000, Tech Prod: 6, Usage: 4, Top: 7
- Increase: Lack of Workers (+20%)

Price Calculation:

Base price adjusted by:
- System tech level vs. commodity production level
- Political system modifiers
- Special resources
- Random events (war, plague, drought, etc.)
- Supply/demand based on player trading history
- Variance: ±5% random fluctuation

Quest System

Major Quests:

Artifact Quest
- Travel to Daled to get artifact
- Deliver to Professor at specific system
- Reward: Credits and reputation
Dragonfly Quest (Multi-stage)
- Stage 1: Deliver package to Baratas
- Stage 2: Take to Melina
- Stage 3: Go to Regulas
- Stage 4: Deliver to Zalkon
- Reward: Lightning Shield
Experiment Quest
- Agree to test experimental equipment
- 10-day time limit
- Side effect: Random fabric rips in space-time
- Reward: Portable Singularity (super warp capability)
Gemulon Quest
- Rescue colonists within 7 days
- Requires specific cargo space
- Time-sensitive
- Reward: Credits and reputation
Japori Disease Quest
- Deliver 10 medicine to plague-stricken Japori
- Must have cargo space
- Reward: Credits and reputation
Jarek Quest
- Transport ambassador Jarek to specific system
- Takes up crew slot
- 12-day time limit
- Reward: Special weapon
Princess Quest (Multi-stage)
- Stage 1: Rescue princess from pirates (Centauri)
- Stage 2: Take to Inthara
- Stage 3: Deliver to Qonos
- Occupies crew slot for duration
- Reward: Quantum Disruptor
Reactor Quest
- Deliver experimental reactor (20 days)
- Uses 10 fuel tanks (can't refuel)
- Time-critical delivery
- Reward: Credits
Scarab Quest
- Encounter and optionally destroy Scarab
- Reward if destroyed: Hull upgrade
Sculpture Quest
- Transport unique sculpture
- Occupies cargo bay
- Reward: Credits and reputation
Space Monster Quest
- Defeat legendary space monster
- Extremely difficult combat
- Reward: Massive bounty and reputation
Wild Quest
- Transport Jonathan Wild
- Takes crew slot
- 12-day limit
- Reward: Reputation

Quest Implementation:

Each quest has state variable (0-N stages)
Time-based triggers (days elapsed)
Location-based triggers (specific systems)
Prerequisite checks (cargo space, crew slots, tech level)
Multiple outcomes (success, failure, partial completion)

Encounter System

Encounter Types:

Police
- Frequency: Based on police record
- Actions: Inspection, bribe, flee, attack, submit
- Inspect cargo for illegal goods (firearms, narcotics)
- Can arrest if criminal record
- May demand payment for violations
Pirates
- Frequency: Common in anarchic/dangerous systems
- Strength: Based on system and player wealth
- Actions: Attack, flee, surrender
- Can steal cargo if player surrenders
- Bounty reward if defeated
Traders
- Peaceful encounters
- May offer to buy/sell cargo in space
- Can trade if both have compatible cargo
Special Events
- Marie Celeste (derelict ship with cargo)
- Captain Ahab (obsessed hunter)
- Captain Conrad (offers quests)
- Captain Huie (famous trader)
- Scorpion encounter
- Alien artifacts
- Bottle with message
- Many more rare encounters

Combat Mechanics:

Turn-based combat
Attack options:
- Auto-attack (computer-controlled)
- Manual fire
- Flee attempt
- Surrender
Hit calculation based on:
- Pilot skill (attacker)
- Pilot skill (defender)
- Ship maneuverability
- Targeting system (if equipped)
Damage calculation:
- Weapon power
- Shield absorption
- Hull damage
- Equipment damage chance
Special tactics:
- Cloaking (avoid detection)
- Disruption (disable opponent)
- Reflection (shield damage back)

Economic System

Player Finances:

Credits (cash on hand)
Debt (loans from banks)
Interest rate: 10% daily on outstanding debt
Maximum debt: 100,000 credits
Debt warning at: 75,000 credits
Bounty earnings (pirate kills)
Insurance premiums and payouts

Insurance System:

Rate: 0.25% of ship value per day
No-claim bonus: Accumulates over 90 days
Covers: Hull damage, destroyed ship
Claim: Resets no-claim counter

Banking:

Get loans (up to 100,000 total)
Pay back loans (minimum payment or full)
Interest accrues daily
Debt collection if excessive

Wealth Progression:

Start with 1,000 credits and Flea ship
Early game: Small cargo trading, single jumps
Mid game: Larger ships, longer trade routes, equipment
Late game: Optimize routes, quest rewards, max ship
End game: 1,000,000+ credits to buy moon and retire

Architectural Comparison

Similarities

Both implementations share these core patterns:

Singleton Game State
- Java: GameState.getInstance()
- C#: Game.CurrentGame
- Centralizes all game data and logic
Procedural Universe Generation
- Same algorithm for placing systems
- Similar distance calculations
- Identical wormhole mechanics
Save/Load Serialization
- Java: Custom serialization via Hashtables
- C#: .NET serialization via Hashtables
- Both support version checking
Dynamic Pricing Engine
- Same commodity price calculations
- Same event modifiers
- Same supply/demand simulation
Quest State Machines
- Integer state variables
- Time-based progression
- Location-based triggers
Equipment Slot System
- Fixed slots per ship type
- Tech level requirements
- Modular weapon/shield/gadget system

Differences

File Organization:

Java: 92 files, highly modular
- Separate packages for datatypes, enums, widgets
- One class per file
- Cleaner separation of concerns
C#: 54 files, more monolithic
- Single massive Game.cs (4000+ lines)
- All enums in one Enums.cs file
- All constants in one Consts.cs file
- Tighter coupling between components

UI Architecture:

Java: Android Activity/Fragment model
- Activity lifecycle management
- Fragment-based screens
- Material Design patterns
- Touch-optimized interface
C#: Windows Forms
- Form-based windows
- Event-driven architecture
- Desktop UI patterns
- Mouse/keyboard interface

Enum Implementation:

Java: Enums as classes with methods

public enum ShipType {
    GNAT(10000, 1, 0, 1, 15, ...);
    private final int cost;
    public int getCost() { return cost; }
}

C#: Traditional enums + data classes

public enum ShipType { Flea, Gnat, ... }
public class ShipSpec {
    public static int[] Costs = { 2000, 10000, ... };
}

Code Style:

Java: Modern Android conventions
- Camel case, getInstance() pattern
- Annotation-based (@Override)
- Null safety considerations
C#: .NET conventions
- Properties with get/set
- LINQ-style collections (where available in 3.5)
- Hungarian notation remnants

Platform Integration:

Java: Deep Android integration
- Shared preferences for settings
- Backup agent for cloud saves
- Resource system for localization
- Multi-DPI drawable support
C#: Windows integration
- Registry or file-based settings
- Local file saves
- Embedded resources
- Fixed-DPI bitmap images

Key Takeaways for Remake

What Works Well

Singleton Pattern for Game State
- Both implementations prove this works for single-save games
- Easy to access from anywhere
- Simplified save/load
Procedural Universe
- Ensures replayability
- Consistent spatial relationships
- Interesting variety
Modular Equipment System
- Flexible ship customization
- Clear upgrade path
- Tech progression
Dynamic Economy
- Engaging trading gameplay
- Meaningful market variations
- Event-driven price changes
Quest State Machines
- Simple integer states are effective
- Easy to save/load
- Clear progression tracking

What Could Be Improved

Code Organization
- C# Game.cs is too monolithic (4000 lines)
- Consider more separation like Java version
- Better encapsulation
UI Responsiveness
- Both have synchronous long operations
- Could benefit from async/await patterns
- Better loading state feedback
Difficulty Balance
- Some quests feel arbitrary
- Combat can be too random
- Economic progression curve steep
Modding Support
- Hard-coded data in both versions
- Could externalize to JSON/XML
- Allow community content
Tutorial/Help
- Complex game with minimal guidance
- Could use progressive tutorials
- Better in-game reference

Recommended Approach for Modern Remake

Technology Stack Considerations:

Web-Based (TypeScript/JavaScript)
- Pros: Cross-platform, easy distribution, progressive web app
- Cons: Performance for large simulations
- Best for: Maximum accessibility
Desktop (C#/.NET 8 or Python)
- Pros: Native performance, rich UI frameworks
- Cons: Platform-specific builds
- Best for: Desktop-first experience
Mobile (React Native or Flutter)
- Pros: True mobile experience, native feel
- Cons: Two codebases (iOS/Android) or framework learning curve
- Best for: Mobile-first remake
Game Engine (Unity or Godot)
- Pros: Built-in systems, visual tools, multi-platform export
- Cons: Overkill for 2D game, larger file size
- Best for: If adding graphics/animations

Recommended Architecture:

Model-View-Controller (MVC) or similar:

Models:
- GameState (singleton)
- Universe (star systems collection)
- Ship, Equipment, Commodity, Quest classes
- SaveManager (serialization)

Controllers:
- GameController (main logic)
- EconomyController (pricing, trading)
- EncounterController (combat, events)
- QuestController (quest management)

Views:
- Separate view layer (React, WPF, etc.)
- Data binding for reactive updates
- Screen components for each game screen

Data-Driven Design:

Store constants in JSON/YAML files
Ship specs, commodity data, quest definitions
Easy balancing and modding
Localization support

Modern Features to Add:

Cloud saves
Achievements/statistics
Multiple save slots
Difficulty customization
Colorblind modes
Keyboard shortcuts
Gamepad support (if applicable)
Sound effects and music
Improved graphics (optional)

Development Workflow

Studying the Reference Code

Start Here:

Understand the data models:
- C#: SpaceTraderSource201/StarSystem.cs
- C#: SpaceTraderSource201/Ship.cs
- Java: space-trader/.../datatypes/Ship.java
Learn the constants:
- C#: SpaceTraderSource201/Consts.cs - Complete reference
- Java: space-trader/.../enumtypes/* - Distributed across enums
Study universe generation:
- C#: Game.cs - GenerateUniverse() method
- Shows placement algorithm, distance checks
Examine pricing:
- C#: Game.cs - CalculatePrices() method
- See how tech level, politics, events affect prices
Understand combat:
- C#: Form_Encounter.cs - Full combat implementation
- Java: EncounterScreen.java - Android version
Review quests:
- C#: Game.cs - Quest state variables and logic scattered throughout
- Java: enumtypes/SpecialEvent.java - Quest definitions

Building the Reference Implementations

Android Version:

cd source/space-trader

# First time setup
# Install Android SDK and set ANDROID_HOME

# Build and install
./gradlew installDebug

# Or build APK only
./gradlew assembleDebug

Windows Version:

cd source/SpaceTraderSource201

# Requires Windows and .NET Framework 3.5 SDK
msbuild Fryz.Apps.SpaceTrader.csproj /p:Configuration=Release

# Or open SpaceTrader.sln in Visual Studio

Extracting Reusable Code

Constants and Data:

Copy Consts.cs values to your format (JSON, etc.)
Extract Strings.cs system names and text
Document equipment specifications from ShipSpec.cs

Algorithms:

Universe generation logic is reusable
Price calculation formulas can be ported
Combat mechanics can be adapted
Quest state machines are language-agnostic

Game Balance:

Ship progression is well-tuned
Commodity prices are balanced
Quest difficulty is reasonable
Use as baseline for your remake

License and Attribution

Both reference implementations are GPL-licensed:

Java/Android version: GPL v3+
C#/Windows version: GPL v2+

When creating a remake:

Must also be GPL-licensed
Must credit original authors (Pieter Spronck and respective port authors)
Must include license text
Can modify and distribute freely
Source code must be available

Original Authors:

Pieter Spronck - Original Palm OS version (2002)
Jay French - Windows port
Russell Wolf - Android port

Resources

Original Game:

Space Trader (Palm OS) by Pieter Spronck
Classic space trading game inspired by Elite

Windows Version:

Website: spacetraderwin.sourceforge.net
Email: spacetrader@frenchfryz.com

Android Version:

Repository: bitbucket.org/brucelet/space-trader
Email: spacetrader@brucelet.com

Inspiration:

Elite (1984) - Original space trading game
Drug Wars / Dope Wars - Economic trading game
Star Traders - Similar concept

Last Updated: 2025-11-18

Purpose: Reference documentation for creating a modernized Space Trader remake based on these two complete implementations.

30 KiB Raw Permalink Blame History

Reference Implementation Notes

Overview

1. Java/Android Implementation

Project Details

Build System

Architecture

Key Components

Android-Specific Features

Code Patterns

2. C#/.NET Windows Implementation

Project Details

Build System

Architecture

Key Components

Resources

Game Systems Deep Dive

Universe Generation

Ship Types

Equipment System

Trade Commodities

Quest System

Encounter System

Economic System

Architectural Comparison

Similarities

Differences

Key Takeaways for Remake

What Works Well

What Could Be Improved

Recommended Approach for Modern Remake

Development Workflow

Studying the Reference Code

Building the Reference Implementations

Extracting Reusable Code

License and Attribution

Resources

30 KiB

Raw Permalink Blame History