Atlaswright

Atlaswright is a Swift / SwiftUI strategy-simulation sandbox for building living fantasy maps. It combines deterministic hex-world generation, SpriteKit rendering, simulation systems, and a screenshot-driven UI test harness so visual changes can be reviewed like code.

The project is still evolving, but it already has terrain generation, multiple map palettes and view modes, generated map assets, saved-world plumbing, fog of war, diplomacy surfaces, command logs, tutorials, and performance tests for larger worlds.

Why It Is Interesting

• Deterministic world generation: the same seed and config produce the same map.
• SpriteKit map rendering: terrain is baked for fast panning and zooming, while borders, features, labels, fog, and selection live on separate layers.
• Simulation-first architecture: live world state is layered over an immutable generated map.
• Visual regression workflow: UI tests generate curated screenshots under docs/screenshots/.
• Multiplatform ambition: the main app targets iOS, macOS, tvOS, and visionOS; watchOS has a separate smoke-build target.

Simulation concurrency is documented in docs/concurrency.md, including the parallelGroup contract for systems that opt into parallel tick execution. For a broader contributor map, start with the architecture guide and the public roadmap.

Screenshots

Biome	Elevation	HUD

Diplomacy	Command Menu	World Creation

Screenshot paths are repo-relative so they render on GitHub and in local Markdown previews.

Name And Compatibility Notes

Atlaswright is the public product name. A few internal compatibility identifiers intentionally remain:

• The Swift target/module and source folder are still MapSim, so tests continue to use @testable import MapSim.
• Some environment variables and test fixtures still use the MAPSIM_ prefix.
• Saved worlds continue to use the legacy .mapsimworld extension and legacy JSON format identifier for migration compatibility.

Renaming those internals would touch hundreds of files and saved-world compatibility tests. Treat them as implementation details until a dedicated module-migration PR exists.

Requirements

• macOS with Xcode 26 or newer.
• XcodeGen: brew install xcodegen.
• Optional: just for the shortcuts in justfile.

Build And Test

For a fuller explanation of which checks to run for different changes, see the testing guide. Setup and simulator workarounds live in troubleshooting.

Generate the Xcode project first:

xcodegen generate

Build the app:

xcodebuild build -project Atlaswright.xcodeproj -scheme Atlaswright -destination 'platform=macOS'
xcodebuild build -project Atlaswright.xcodeproj -scheme Atlaswright -destination 'generic/platform=iOS Simulator'

Run unit tests:

xcodebuild test -project Atlaswright.xcodeproj -scheme Atlaswright -destination 'platform=macOS' -only-testing:MapSimTests

Run Swift Package tests used by coverage and strict-concurrency checks:

swift test
swift test -Xswiftc -strict-concurrency=complete

Run repository gates before opening a pull request:

./scripts/check-file-length.sh
./scripts/check-swiftdoc-coverage.py
./scripts/check-previews.sh
./scripts/check-determinism.sh
./scripts/lint-localization.py
./scripts/check-public-readiness.py

For UI or rendering changes, refresh and inspect screenshots:

./scripts/ui-screenshots-ios.sh
./scripts/update-readme-screenshots.sh

Project Layout

MapSim/                  Swift app sources; internal module remains MapSim
MapSimTests/             Swift Testing unit tests
MapSimUITests/           XCUITest screenshot harness
Shared/                  IDs and helpers shared with UI tests
docs/                    Architecture notes, screenshots, generated-asset docs
scripts/                 Build, lint, screenshot, and CI helper scripts
project.yml              XcodeGen project definition
Package.swift            SwiftPM package used for package-level tests

Continuous Integration

GitHub Actions are intentionally not enabled for the first public mirror. A commented-out scaffold is retained at .github/workflows/build.yml, but public contributors should build and test locally with the commands above until the project is ready to publish a stable public CI contract.

The .gitea/ directory is retained for upstream maintainers who use Gitea/OpenJIRA automation. Those workflows may rely on private runner labels, private secrets, or internal artifact import endpoints and are not required for public GitHub contributions.

Privacy

Atlaswright runs on-device and does not collect user data, use analytics, or contact tracking domains. See PRIVACY.md for the public summary and docs/privacy.md for maintainer verification notes.

Contributing

See CONTRIBUTING.md, SUPPORT.md, the testing guide, and the public roadmap. By participating, you agree to follow the Code of Conduct. Security reports should follow SECURITY.md. Project decisions and release expectations are documented in GOVERNANCE.md, CHANGELOG.md, and docs/release-process.md. Public issue labels and triage expectations live in docs/triage.md.

Maintainers preparing the first public GitHub mirror should use the public mirror checklist and GitHub mirror settings guide.

License

Atlaswright is available under the MIT License.