mirror of
https://github.com/pawelorzech/MacTorn.git
synced 2026-01-29 19:54:27 +00:00
docs: Add comprehensive GitHub wiki documentation
Create wiki/ directory with 11 markdown pages covering: - Home, Installation, Getting Started guides - Features documentation for all tabs - API Setup with permissions and security - Configuration options and settings - Troubleshooting and FAQ - Development guide with architecture overview - Changelog with version history - Sidebar navigation
This commit is contained in:
Paweł Orzech
parent
e10add9474
commit
715f0877ff
11 changed files with 1504 additions and 0 deletions
139
wiki/API-Setup.md
Normal file
139
wiki/API-Setup.md
Normal file
|
|
@ -0,0 +1,139 @@
|
||||||
|
# API Setup
|
||||||
|
|
||||||
|
MacTorn requires a Torn API key to fetch your game data. This guide explains how to generate a key and what data MacTorn accesses.
|
||||||
|
|
||||||
|
## Generating an API Key
|
||||||
|
|
||||||
|
### Step-by-Step
|
||||||
|
|
||||||
|
1. **Log into Torn** at https://www.torn.com
|
||||||
|
2. Go to **Settings** in the sidebar
|
||||||
|
3. Click the **API Keys** tab, or go directly to: https://www.torn.com/preferences.php#tab=api
|
||||||
|
4. Under "Create New Key":
|
||||||
|
- Enter a name (e.g., "MacTorn")
|
||||||
|
- Select access level (see below)
|
||||||
|
5. Click **Create**
|
||||||
|
6. **Copy the 16-character key** that appears
|
||||||
|
|
||||||
|
### Access Levels
|
||||||
|
|
||||||
|
Torn offers several API access levels:
|
||||||
|
|
||||||
|
| Level | Recommended | Notes |
|
||||||
|
|-------|-------------|-------|
|
||||||
|
| **Full Access** | Yes | Simplest option, works with all MacTorn features |
|
||||||
|
| **Limited Access** | Yes | Works if you select required permissions |
|
||||||
|
| **Custom** | Possible | Select specific permissions |
|
||||||
|
|
||||||
|
### Required Permissions
|
||||||
|
|
||||||
|
If using Limited or Custom access, MacTorn requires these selections:
|
||||||
|
|
||||||
|
| Permission | Used For |
|
||||||
|
|------------|----------|
|
||||||
|
| `basic` | Player name, ID, basic info |
|
||||||
|
| `bars` | Energy, Nerve, Happy, Life bars |
|
||||||
|
| `cooldowns` | Drug, Medical, Booster timers |
|
||||||
|
| `travel` | Travel status and destination |
|
||||||
|
| `profile` | Battle stats, faction info |
|
||||||
|
| `events` | Recent events feed |
|
||||||
|
| `messages` | Unread message count |
|
||||||
|
| `money` | Cash, vault, points, tokens |
|
||||||
|
| `battlestats` | Strength, Defense, Speed, Dexterity |
|
||||||
|
| `attacks` | Recent attack history |
|
||||||
|
| `properties` | Property information |
|
||||||
|
|
||||||
|
For watchlist functionality:
|
||||||
|
| Permission | Used For |
|
||||||
|
|------------|----------|
|
||||||
|
| `market` (v2) | Item prices from Item Market |
|
||||||
|
|
||||||
|
## Entering Your API Key in MacTorn
|
||||||
|
|
||||||
|
1. Click the MacTorn icon in your menu bar
|
||||||
|
2. Go to the **Settings** tab
|
||||||
|
3. Enter your API key in the text field
|
||||||
|
4. Click **Save & Connect**
|
||||||
|
|
||||||
|
MacTorn will immediately attempt to fetch your data. If successful, you'll see your status appear in the Status tab.
|
||||||
|
|
||||||
|
## API Data Usage Disclosure
|
||||||
|
|
||||||
|
In compliance with Torn's API Terms of Service, here is exactly what MacTorn accesses:
|
||||||
|
|
||||||
|
### User Endpoint (v1)
|
||||||
|
|
||||||
|
MacTorn calls the user endpoint with these selections:
|
||||||
|
|
||||||
|
```
|
||||||
|
/user/?selections=basic,bars,cooldowns,travel,profile,events,messages,money,battlestats,attacks,properties
|
||||||
|
```
|
||||||
|
|
||||||
|
**Purpose:** Display your player status, bars, cooldowns, travel info, faction, events, messages, finances, battle stats, and attacks.
|
||||||
|
|
||||||
|
### Faction Endpoint (v1)
|
||||||
|
|
||||||
|
When you have faction data:
|
||||||
|
|
||||||
|
```
|
||||||
|
/faction/?selections=basic,chain
|
||||||
|
```
|
||||||
|
|
||||||
|
**Purpose:** Display faction name, chain status, and war information.
|
||||||
|
|
||||||
|
### Market Endpoint (v2)
|
||||||
|
|
||||||
|
For watchlist items:
|
||||||
|
|
||||||
|
```
|
||||||
|
/v2/market/{itemId}?selections=itemmarket,bazaar
|
||||||
|
```
|
||||||
|
|
||||||
|
**Purpose:** Fetch current market prices for items you're watching.
|
||||||
|
|
||||||
|
## Security Best Practices
|
||||||
|
|
||||||
|
### Do
|
||||||
|
|
||||||
|
- **Use a dedicated key** for MacTorn that you can revoke if needed
|
||||||
|
- **Limit permissions** if you don't need all features
|
||||||
|
- **Keep your key private** - never share it
|
||||||
|
|
||||||
|
### Don't
|
||||||
|
|
||||||
|
- Don't use your main API key for third-party apps
|
||||||
|
- Don't share your API key with others
|
||||||
|
- Don't commit your key to git or public repositories
|
||||||
|
|
||||||
|
## Key Storage
|
||||||
|
|
||||||
|
MacTorn stores your API key locally using macOS's `UserDefaults` system. The key:
|
||||||
|
|
||||||
|
- Is stored on your Mac only
|
||||||
|
- Is **not** transmitted anywhere except to Torn's API
|
||||||
|
- Is **not** backed up to iCloud
|
||||||
|
- Can be removed by clearing MacTorn's preferences
|
||||||
|
|
||||||
|
## Revoking Access
|
||||||
|
|
||||||
|
If you need to stop MacTorn from accessing your Torn data:
|
||||||
|
|
||||||
|
1. Go to Torn API settings: https://www.torn.com/preferences.php#tab=api
|
||||||
|
2. Find your MacTorn key
|
||||||
|
3. Click **Delete** next to it
|
||||||
|
|
||||||
|
MacTorn will show an error state until a new valid key is entered.
|
||||||
|
|
||||||
|
## API Rate Limits
|
||||||
|
|
||||||
|
Torn's API has rate limits. MacTorn is designed to respect these:
|
||||||
|
|
||||||
|
- Default refresh is 30 seconds
|
||||||
|
- Minimum refresh is 15 seconds
|
||||||
|
- Each refresh makes 1-3 API calls depending on features used
|
||||||
|
|
||||||
|
If you're using multiple Torn apps, you may want to use longer refresh intervals.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next:** [[Configuration]] - Customize your settings
|
||||||
133
wiki/Changelog.md
Normal file
133
wiki/Changelog.md
Normal file
|
|
@ -0,0 +1,133 @@
|
||||||
|
# Changelog
|
||||||
|
|
||||||
|
All notable changes to MacTorn are documented here.
|
||||||
|
|
||||||
|
## [v1.4.4] - Latest
|
||||||
|
|
||||||
|
### Fixed
|
||||||
|
- Fixed watchlist item mutation to update via copy for proper SwiftUI state updates
|
||||||
|
|
||||||
|
## [v1.4.3]
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Improved accessibility support and updated README documentation
|
||||||
|
|
||||||
|
## [v1.4.2]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Universal Binary support for Intel (x86_64) and Apple Silicon (arm64) Macs
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Cooldown labels now display as text instead of icons for better readability
|
||||||
|
|
||||||
|
## [v1.4.1]
|
||||||
|
|
||||||
|
### Fixed
|
||||||
|
- Resolved Credits view height being cut off in MenuBarExtra window
|
||||||
|
- Fixed SwiftUI constraint update loop in MenuBarExtra
|
||||||
|
|
||||||
|
## [v1.4]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **Travel Tab** - Dedicated tab for travel management
|
||||||
|
- Live countdown timer updating every second
|
||||||
|
- Flight progress bar
|
||||||
|
- Quick travel destination picker (all 11 Torn destinations)
|
||||||
|
- Pre-arrival notifications (2min, 1min, 30sec, 10sec before landing)
|
||||||
|
- Country flags for all destinations
|
||||||
|
- **Menu bar travel display** - Shows airplane + flag + countdown when flying (e.g., "✈️🇬🇧 5:32")
|
||||||
|
|
||||||
|
## [v1.3]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Live countdown timers for cooldowns
|
||||||
|
- Credits page accessible from Settings
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Optimized startup with non-blocking data fetching
|
||||||
|
|
||||||
|
## [v1.2.5]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- API usage disclosure in Settings (Torn API ToS compliance)
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Life progress bar color changed to blue for better distinction
|
||||||
|
|
||||||
|
## [v1.2]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **Watchlist feature** - Track item prices from Item Market
|
||||||
|
- Uses Torn API v2 for market data
|
||||||
|
- Shows lowest price and quantity
|
||||||
|
- Price change indicators
|
||||||
|
- Quick add from popular items list
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Various UI improvements
|
||||||
|
|
||||||
|
## [v1.1]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Update checker - Automatic notification when new version available
|
||||||
|
- Launch at Login option
|
||||||
|
|
||||||
|
### Improved
|
||||||
|
- Notification system reliability
|
||||||
|
|
||||||
|
## [v1.0]
|
||||||
|
|
||||||
|
### Initial Release
|
||||||
|
|
||||||
|
- **Status Tab** with:
|
||||||
|
- Energy, Nerve, Happy, Life bars
|
||||||
|
- Cooldown timers (Drug, Medical, Booster)
|
||||||
|
- Hospital/Jail status badges
|
||||||
|
- Unread messages badge
|
||||||
|
- Chain timer
|
||||||
|
- Events feed
|
||||||
|
- 8 quick links
|
||||||
|
|
||||||
|
- **Money Tab** with:
|
||||||
|
- Cash, Vault, Points, Tokens display
|
||||||
|
- Quick action buttons
|
||||||
|
|
||||||
|
- **Attacks Tab** with:
|
||||||
|
- Battle stats display
|
||||||
|
- Recent attacks list
|
||||||
|
|
||||||
|
- **Faction Tab** with:
|
||||||
|
- Faction info
|
||||||
|
- Chain status
|
||||||
|
- War status
|
||||||
|
|
||||||
|
- **Settings Tab** with:
|
||||||
|
- API key management
|
||||||
|
- Refresh interval selection
|
||||||
|
- Appearance mode (System/Light/Dark)
|
||||||
|
|
||||||
|
- **Core Features**:
|
||||||
|
- Menu bar app with dynamic icon
|
||||||
|
- Configurable notifications
|
||||||
|
- macOS 13.0+ support
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version History Summary
|
||||||
|
|
||||||
|
| Version | Highlights |
|
||||||
|
|---------|-----------|
|
||||||
|
| v1.4.4 | Watchlist mutation fix |
|
||||||
|
| v1.4.3 | Accessibility improvements |
|
||||||
|
| v1.4.2 | Universal Binary support |
|
||||||
|
| v1.4.1 | UI bug fixes |
|
||||||
|
| v1.4 | Travel tab with live countdown |
|
||||||
|
| v1.3 | Live cooldown timers |
|
||||||
|
| v1.2.5 | API ToS compliance |
|
||||||
|
| v1.2 | Watchlist feature |
|
||||||
|
| v1.1 | Update checker |
|
||||||
|
| v1.0 | Initial release |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
For the latest version, visit the [Releases page](https://github.com/pawelorzech/MacTorn/releases).
|
||||||
167
wiki/Configuration.md
Normal file
167
wiki/Configuration.md
Normal file
|
|
@ -0,0 +1,167 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
MacTorn offers several configuration options to customize your experience. All settings are found in the **Settings** tab.
|
||||||
|
|
||||||
|
## Refresh Interval
|
||||||
|
|
||||||
|
Control how often MacTorn fetches data from Torn's API.
|
||||||
|
|
||||||
|
| Interval | Best For |
|
||||||
|
|----------|----------|
|
||||||
|
| **15 seconds** | Active players who need real-time updates |
|
||||||
|
| **30 seconds** | Balanced usage (default) |
|
||||||
|
| **60 seconds** | Casual monitoring |
|
||||||
|
| **2 minutes** | Minimal API usage, background monitoring |
|
||||||
|
|
||||||
|
**Note:** Shorter intervals use more API calls. If you use multiple Torn apps, consider longer intervals to avoid rate limits.
|
||||||
|
|
||||||
|
### Changing Refresh Interval
|
||||||
|
|
||||||
|
1. Open MacTorn (click menu bar icon)
|
||||||
|
2. Go to **Settings** tab
|
||||||
|
3. Click your preferred interval in the segmented control
|
||||||
|
|
||||||
|
The change takes effect immediately.
|
||||||
|
|
||||||
|
## Appearance Mode
|
||||||
|
|
||||||
|
Choose how MacTorn appears:
|
||||||
|
|
||||||
|
| Mode | Behavior |
|
||||||
|
|------|----------|
|
||||||
|
| **System** | Follows macOS appearance (Light/Dark) |
|
||||||
|
| **Light** | Always use light theme |
|
||||||
|
| **Dark** | Always use dark theme |
|
||||||
|
|
||||||
|
### Setting Appearance
|
||||||
|
|
||||||
|
1. Open MacTorn
|
||||||
|
2. Go to **Settings** tab
|
||||||
|
3. Select your preferred mode from the picker
|
||||||
|
|
||||||
|
## Accessibility Settings
|
||||||
|
|
||||||
|
### Reduce Transparency
|
||||||
|
|
||||||
|
When enabled, MacTorn uses solid backgrounds instead of translucent materials. This improves readability for users who prefer less visual complexity.
|
||||||
|
|
||||||
|
**To enable:**
|
||||||
|
1. Open MacTorn Settings
|
||||||
|
2. Toggle **Reduce Transparency** ON
|
||||||
|
|
||||||
|
**System-wide setting:** MacTorn also respects the macOS "Reduce Transparency" setting found in System Settings > Accessibility > Display.
|
||||||
|
|
||||||
|
## Launch at Login
|
||||||
|
|
||||||
|
Start MacTorn automatically when you log into your Mac.
|
||||||
|
|
||||||
|
**To enable:**
|
||||||
|
1. Open MacTorn Settings
|
||||||
|
2. Toggle **Launch at Login** ON
|
||||||
|
|
||||||
|
MacTorn will now appear in your menu bar after every restart/login.
|
||||||
|
|
||||||
|
## Notification Settings
|
||||||
|
|
||||||
|
MacTorn can send macOS notifications for various events.
|
||||||
|
|
||||||
|
### Available Notifications
|
||||||
|
|
||||||
|
| Notification | When Triggered |
|
||||||
|
|--------------|----------------|
|
||||||
|
| Energy threshold | Energy reaches a certain level |
|
||||||
|
| Nerve threshold | Nerve reaches a certain level |
|
||||||
|
| Cooldown ready | Drug/Medical/Booster cooldown completes |
|
||||||
|
| Travel landing | Arriving at destination |
|
||||||
|
| Chain expiring | Chain timer running low |
|
||||||
|
| Hospital release | Released from hospital |
|
||||||
|
| Jail release | Released from jail |
|
||||||
|
|
||||||
|
### Travel Pre-Arrival Alerts
|
||||||
|
|
||||||
|
Configure notifications before landing (found in Travel tab):
|
||||||
|
|
||||||
|
| Alert | When |
|
||||||
|
|-------|------|
|
||||||
|
| 2 minutes | 2 minutes before arrival |
|
||||||
|
| 1 minute | 1 minute before arrival |
|
||||||
|
| 30 seconds | 30 seconds before arrival |
|
||||||
|
| 10 seconds | 10 seconds before arrival |
|
||||||
|
|
||||||
|
Enable/disable each independently in the Travel tab under "Pre-Arrival Alerts".
|
||||||
|
|
||||||
|
### Enabling macOS Notifications
|
||||||
|
|
||||||
|
For MacTorn notifications to appear, ensure they're enabled in macOS:
|
||||||
|
|
||||||
|
1. Open **System Settings**
|
||||||
|
2. Go to **Notifications**
|
||||||
|
3. Find **MacTorn** in the list
|
||||||
|
4. Ensure **Allow Notifications** is ON
|
||||||
|
5. Configure banner style, sounds, etc. as desired
|
||||||
|
|
||||||
|
## Watchlist Configuration
|
||||||
|
|
||||||
|
The Watchlist tab tracks item prices from Torn's Item Market.
|
||||||
|
|
||||||
|
### Adding Items
|
||||||
|
|
||||||
|
1. Go to **Watchlist** tab
|
||||||
|
2. Click the **+** button
|
||||||
|
3. Select an item from the preset list:
|
||||||
|
- Xanax
|
||||||
|
- FHC (Feathery Hotel Coupon)
|
||||||
|
- Donator Pack
|
||||||
|
- Drug Pack
|
||||||
|
- Energy Drink
|
||||||
|
- First Aid Kit
|
||||||
|
|
||||||
|
### Removing Items
|
||||||
|
|
||||||
|
Click the **x** button next to any watched item to remove it.
|
||||||
|
|
||||||
|
### Manual Refresh
|
||||||
|
|
||||||
|
Click the refresh icon (circular arrow) in the Watchlist header to manually update prices.
|
||||||
|
|
||||||
|
## Quick Links
|
||||||
|
|
||||||
|
The Status tab includes 8 quick links. Currently these are preset to common Torn pages:
|
||||||
|
|
||||||
|
- Gym
|
||||||
|
- Items
|
||||||
|
- Properties
|
||||||
|
- Missions
|
||||||
|
- Crimes
|
||||||
|
- Jail
|
||||||
|
- Hospital
|
||||||
|
- Casino
|
||||||
|
|
||||||
|
## Data Storage
|
||||||
|
|
||||||
|
MacTorn stores configuration locally:
|
||||||
|
|
||||||
|
| Data | Storage Method |
|
||||||
|
|------|----------------|
|
||||||
|
| API Key | UserDefaults (local) |
|
||||||
|
| Refresh Interval | UserDefaults |
|
||||||
|
| Appearance Mode | UserDefaults |
|
||||||
|
| Reduce Transparency | UserDefaults |
|
||||||
|
| Launch at Login | macOS SMAppService |
|
||||||
|
| Notification Rules | UserDefaults |
|
||||||
|
| Watchlist Items | UserDefaults |
|
||||||
|
|
||||||
|
**Privacy:** No data is sent anywhere except to Torn's API servers.
|
||||||
|
|
||||||
|
## Resetting Configuration
|
||||||
|
|
||||||
|
To reset all settings to defaults:
|
||||||
|
|
||||||
|
1. Quit MacTorn
|
||||||
|
2. Open Terminal
|
||||||
|
3. Run: `defaults delete com.bombel.MacTorn`
|
||||||
|
4. Relaunch MacTorn
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next:** [[Troubleshooting]] - Solutions to common issues
|
||||||
250
wiki/Development.md
Normal file
250
wiki/Development.md
Normal file
|
|
@ -0,0 +1,250 @@
|
||||||
|
# Development
|
||||||
|
|
||||||
|
This guide covers building MacTorn from source and contributing to the project.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- **macOS 13.0+** (Ventura or later)
|
||||||
|
- **Xcode 15+** (with Swift 5)
|
||||||
|
- **Git**
|
||||||
|
|
||||||
|
## Getting the Source
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/pawelorzech/MacTorn.git
|
||||||
|
cd MacTorn/MacTorn
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
### Using Xcode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
open MacTorn.xcodeproj
|
||||||
|
```
|
||||||
|
|
||||||
|
Press `Cmd + R` to build and run.
|
||||||
|
|
||||||
|
### Using Make
|
||||||
|
|
||||||
|
MacTorn includes a Makefile for common operations:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build Debug version
|
||||||
|
make build
|
||||||
|
|
||||||
|
# Build Release (Universal Binary)
|
||||||
|
make release
|
||||||
|
|
||||||
|
# Run unit tests
|
||||||
|
make test
|
||||||
|
|
||||||
|
# Run UI tests
|
||||||
|
make test-ui
|
||||||
|
|
||||||
|
# Run all tests
|
||||||
|
make test-all
|
||||||
|
|
||||||
|
# Clean build artifacts
|
||||||
|
make clean
|
||||||
|
```
|
||||||
|
|
||||||
|
All make commands use `xcodebuild` with code signing disabled (`CODE_SIGN_IDENTITY="-"`).
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
MacTorn/
|
||||||
|
├── MacTorn/ # Main app target
|
||||||
|
│ ├── MacTornApp.swift # App entry point
|
||||||
|
│ ├── ViewModels/
|
||||||
|
│ │ └── AppState.swift # Central state manager
|
||||||
|
│ ├── Models/
|
||||||
|
│ │ └── TornModels.swift # Data models & API config
|
||||||
|
│ ├── Views/
|
||||||
|
│ │ ├── ContentView.swift # Main tab container
|
||||||
|
│ │ ├── StatusView.swift # Status tab
|
||||||
|
│ │ ├── TravelView.swift # Travel tab
|
||||||
|
│ │ ├── MoneyView.swift # Money tab
|
||||||
|
│ │ ├── AttacksView.swift # Attacks tab
|
||||||
|
│ │ ├── FactionView.swift # Faction tab
|
||||||
|
│ │ ├── WatchlistView.swift # Watchlist tab
|
||||||
|
│ │ ├── SettingsView.swift # Settings tab
|
||||||
|
│ │ └── Components/ # Reusable components
|
||||||
|
│ ├── Utilities/
|
||||||
|
│ │ ├── NotificationManager.swift
|
||||||
|
│ │ ├── LaunchAtLoginManager.swift
|
||||||
|
│ │ ├── ShortcutsManager.swift
|
||||||
|
│ │ └── SoundManager.swift
|
||||||
|
│ ├── Networking/
|
||||||
|
│ │ └── NetworkSession.swift # Network abstraction
|
||||||
|
│ └── Helpers/
|
||||||
|
│ └── TransparencyEnvironment.swift
|
||||||
|
├── MacTornTests/ # Unit tests
|
||||||
|
│ ├── Models/
|
||||||
|
│ ├── ViewModels/
|
||||||
|
│ ├── Mocks/
|
||||||
|
│ │ └── MockNetworkSession.swift
|
||||||
|
│ └── Fixtures/
|
||||||
|
│ └── TornAPIFixtures.swift
|
||||||
|
└── MacTornUITests/ # UI tests
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
### App Structure
|
||||||
|
|
||||||
|
MacTorn uses SwiftUI with the `@main` attribute and `MenuBarExtra` scene for the menu bar interface.
|
||||||
|
|
||||||
|
### State Management
|
||||||
|
|
||||||
|
**AppState** (`AppState.swift`) is the central state manager:
|
||||||
|
- Uses `@MainActor` for thread safety
|
||||||
|
- Handles API polling via Combine's `Timer.publish`
|
||||||
|
- Manages data parsing, notifications, and watchlist
|
||||||
|
- Uses dependency injection via `NetworkSession` protocol
|
||||||
|
|
||||||
|
### Networking
|
||||||
|
|
||||||
|
The `NetworkSession` protocol abstracts network calls:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
protocol NetworkSession {
|
||||||
|
func data(from url: URL) async throws -> (Data, URLResponse)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This allows injecting `URLSession` for production and `MockNetworkSession` for testing.
|
||||||
|
|
||||||
|
### Data Models
|
||||||
|
|
||||||
|
All models are in `TornModels.swift`:
|
||||||
|
- `TornResponse` - Main API response
|
||||||
|
- `Bar` - Energy/Nerve/Happy/Life bar
|
||||||
|
- `Travel` - Travel status
|
||||||
|
- `Status` - Player status
|
||||||
|
- `Chain` - Faction chain
|
||||||
|
- `WatchlistItem` - Watched item with price
|
||||||
|
|
||||||
|
`TornAPI` enum contains endpoint configurations.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Writing Unit Tests
|
||||||
|
|
||||||
|
Tests use `MockNetworkSession` for API testing:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
import XCTest
|
||||||
|
@testable import MacTorn
|
||||||
|
|
||||||
|
final class MyTests: XCTestCase {
|
||||||
|
func testExample() async throws {
|
||||||
|
let mockSession = MockNetworkSession()
|
||||||
|
let appState = AppState(session: mockSession)
|
||||||
|
|
||||||
|
try mockSession.setSuccessResponse(json: TornAPIFixtures.validFullResponse)
|
||||||
|
|
||||||
|
await appState.refreshNow()
|
||||||
|
|
||||||
|
XCTAssertNotNil(appState.data)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Fixtures
|
||||||
|
|
||||||
|
`TornAPIFixtures.swift` contains sample JSON responses for testing.
|
||||||
|
|
||||||
|
### Running Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Unit tests only
|
||||||
|
make test
|
||||||
|
|
||||||
|
# UI tests only
|
||||||
|
make test-ui
|
||||||
|
|
||||||
|
# All tests
|
||||||
|
make test-all
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Patterns
|
||||||
|
|
||||||
|
### API Polling
|
||||||
|
|
||||||
|
`AppState.startPolling()` uses Combine's Timer:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
func startPolling() {
|
||||||
|
timerCancellable?.cancel()
|
||||||
|
timerCancellable = Timer.publish(every: TimeInterval(refreshInterval), on: .main, in: .common)
|
||||||
|
.autoconnect()
|
||||||
|
.sink { [weak self] _ in
|
||||||
|
Task { @MainActor in
|
||||||
|
await self?.fetchData()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Live Countdown
|
||||||
|
|
||||||
|
Travel timer updates every second independently of API polling:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
travelTimerCancellable = Timer.publish(every: 1, on: .main, in: .common)
|
||||||
|
.autoconnect()
|
||||||
|
.sink { [weak self] _ in
|
||||||
|
self?.updateTravelCountdown()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Accessibility
|
||||||
|
|
||||||
|
`TransparencyEnvironment.swift` provides a custom environment key:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
@Environment(\.reduceTransparency) private var reduceTransparency
|
||||||
|
```
|
||||||
|
|
||||||
|
Views use this to adjust backgrounds based on accessibility settings.
|
||||||
|
|
||||||
|
### State Persistence
|
||||||
|
|
||||||
|
- `@AppStorage` for simple values (API key, refresh interval, appearance)
|
||||||
|
- `UserDefaults` for complex data (notification rules, watchlist)
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
### Workflow
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a feature branch (`git checkout -b feature/my-feature`)
|
||||||
|
3. Make changes
|
||||||
|
4. Run tests (`make test-all`)
|
||||||
|
5. Commit with descriptive message
|
||||||
|
6. Push to your fork
|
||||||
|
7. Create a Pull Request
|
||||||
|
|
||||||
|
### Code Style
|
||||||
|
|
||||||
|
- Use Swift standard naming conventions
|
||||||
|
- Keep views focused and extract components
|
||||||
|
- Add tests for new functionality
|
||||||
|
- Update documentation as needed
|
||||||
|
|
||||||
|
### Pull Request Guidelines
|
||||||
|
|
||||||
|
- Describe what changes were made and why
|
||||||
|
- Reference any related issues
|
||||||
|
- Ensure all tests pass
|
||||||
|
- Keep changes focused (one feature/fix per PR)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MacTorn is released under the MIT License. See [LICENSE](https://github.com/pawelorzech/MacTorn/blob/main/LICENSE) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**See Also:** [[Changelog]] for version history
|
||||||
124
wiki/FAQ.md
Normal file
124
wiki/FAQ.md
Normal file
|
|
@ -0,0 +1,124 @@
|
||||||
|
# Frequently Asked Questions
|
||||||
|
|
||||||
|
## General
|
||||||
|
|
||||||
|
### What is MacTorn?
|
||||||
|
|
||||||
|
MacTorn is a native macOS menu bar application that monitors your Torn game status. It displays energy bars, travel timers, chain status, and more without requiring a browser tab.
|
||||||
|
|
||||||
|
### Is MacTorn free?
|
||||||
|
|
||||||
|
Yes, MacTorn is free and open source under the MIT License.
|
||||||
|
|
||||||
|
### Does MacTorn work on Windows/Linux?
|
||||||
|
|
||||||
|
No, MacTorn is a native macOS application and only works on Macs running macOS 13.0 or later.
|
||||||
|
|
||||||
|
### Does MacTorn work on Intel Macs?
|
||||||
|
|
||||||
|
Yes! MacTorn is a Universal Binary that runs natively on both Intel (x86_64) and Apple Silicon (arm64) Macs.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Why can't I open the app?
|
||||||
|
|
||||||
|
macOS Gatekeeper blocks unsigned apps. Right-click the app and select "Open", or go to System Settings > Privacy & Security and click "Open Anyway".
|
||||||
|
|
||||||
|
See [[Troubleshooting]] for detailed steps.
|
||||||
|
|
||||||
|
### Where do I download MacTorn?
|
||||||
|
|
||||||
|
Download from the [GitHub Releases page](https://github.com/pawelorzech/MacTorn/releases).
|
||||||
|
|
||||||
|
### How do I update MacTorn?
|
||||||
|
|
||||||
|
When a new version is available, you'll see a notification in the Settings tab. Click "Download Update" to get the latest version from GitHub, then replace your old app with the new one.
|
||||||
|
|
||||||
|
## API & Security
|
||||||
|
|
||||||
|
### Is my API key safe?
|
||||||
|
|
||||||
|
Yes. Your API key is:
|
||||||
|
- Stored locally on your Mac only
|
||||||
|
- Never transmitted anywhere except to Torn's official API
|
||||||
|
- Not synced to iCloud or any cloud service
|
||||||
|
|
||||||
|
### What API permissions does MacTorn need?
|
||||||
|
|
||||||
|
For full functionality: basic, bars, cooldowns, travel, profile, events, messages, money, battlestats, attacks, properties, and market access.
|
||||||
|
|
||||||
|
You can use "Full Access" or select specific permissions. See [[API-Setup]] for details.
|
||||||
|
|
||||||
|
### Can MacTorn perform actions on my account?
|
||||||
|
|
||||||
|
No. MacTorn is read-only. It can only view your data - it cannot attack, travel, buy items, or perform any actions on your behalf.
|
||||||
|
|
||||||
|
### Does MacTorn violate Torn's rules?
|
||||||
|
|
||||||
|
No. MacTorn uses Torn's official public API as intended. It follows all API terms of service.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### How often does MacTorn update data?
|
||||||
|
|
||||||
|
By default, every 30 seconds. You can change this to 15s, 60s, or 2m in Settings.
|
||||||
|
|
||||||
|
### How do I get notifications?
|
||||||
|
|
||||||
|
MacTorn sends notifications through macOS. Ensure notifications are enabled in System Settings > Notifications > MacTorn.
|
||||||
|
|
||||||
|
### Why is the travel countdown in my menu bar?
|
||||||
|
|
||||||
|
When you're traveling, MacTorn shows a live countdown (e.g., "✈️🇬🇧 5:32") so you can always see when you'll land without opening the app.
|
||||||
|
|
||||||
|
### Can I track custom items in the watchlist?
|
||||||
|
|
||||||
|
Currently, the watchlist offers preset popular items. Custom item IDs may be added in future versions.
|
||||||
|
|
||||||
|
### Does MacTorn show chain alerts?
|
||||||
|
|
||||||
|
Yes. When your faction has an active chain, MacTorn displays the chain count and timeout timer in the Status tab.
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Why do I see a warning triangle icon?
|
||||||
|
|
||||||
|
The triangle icon indicates an error, usually an API issue. Open MacTorn and check the Settings tab for error messages.
|
||||||
|
|
||||||
|
### Notifications aren't working. Why?
|
||||||
|
|
||||||
|
1. Check macOS notification settings (System Settings > Notifications > MacTorn)
|
||||||
|
2. Ensure notifications are allowed
|
||||||
|
3. For travel alerts, enable them in the Travel tab
|
||||||
|
|
||||||
|
### The app is using a lot of battery/CPU. Is this normal?
|
||||||
|
|
||||||
|
No. MacTorn should use minimal resources. Try quitting and relaunching. If the issue persists, please file a bug report.
|
||||||
|
|
||||||
|
### How do I completely remove MacTorn?
|
||||||
|
|
||||||
|
1. Quit MacTorn
|
||||||
|
2. Delete MacTorn.app from Applications
|
||||||
|
3. (Optional) Clear preferences: `defaults delete com.bombel.MacTorn` in Terminal
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
### How do I report a bug?
|
||||||
|
|
||||||
|
File an issue on [GitHub](https://github.com/pawelorzech/MacTorn/issues) with:
|
||||||
|
- Your macOS version
|
||||||
|
- MacTorn version
|
||||||
|
- Steps to reproduce
|
||||||
|
- Screenshots if helpful
|
||||||
|
|
||||||
|
### How can I support the developer?
|
||||||
|
|
||||||
|
Send some Xanax or cash to **bombel** [[2362436](https://www.torn.com/profiles.php?XID=2362436)] in-game!
|
||||||
|
|
||||||
|
### Is there a Discord or community?
|
||||||
|
|
||||||
|
Currently, support is through GitHub issues. Join the Torn Discord if you want to discuss with other players.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**See Also:** [[Troubleshooting]] for detailed solutions
|
||||||
253
wiki/Features.md
Normal file
253
wiki/Features.md
Normal file
|
|
@ -0,0 +1,253 @@
|
||||||
|
# Features
|
||||||
|
|
||||||
|
MacTorn offers a comprehensive set of features for monitoring your Torn status. This page details all available features organized by tab.
|
||||||
|
|
||||||
|
## Status Tab
|
||||||
|
|
||||||
|
The Status tab is your main dashboard showing vital information at a glance.
|
||||||
|
|
||||||
|
### Progress Bars
|
||||||
|
|
||||||
|
Real-time display of your four main stats with color-coded progress:
|
||||||
|
|
||||||
|
| Bar | Color | Description |
|
||||||
|
|-----|-------|-------------|
|
||||||
|
| **Energy** | Orange/Yellow | Your energy level and regeneration |
|
||||||
|
| **Nerve** | Red | Your nerve level |
|
||||||
|
| **Happy** | Pink | Your happiness level |
|
||||||
|
| **Life** | Blue | Your current health |
|
||||||
|
|
||||||
|
Each bar shows:
|
||||||
|
- Current value / Maximum value
|
||||||
|
- Visual progress indicator
|
||||||
|
- Fill color changes as bar approaches full
|
||||||
|
|
||||||
|
### Cooldown Timers
|
||||||
|
|
||||||
|
Live countdown timers for:
|
||||||
|
- **Drug Cooldown** - Time until you can use drugs again
|
||||||
|
- **Medical Cooldown** - Time until medical items are available
|
||||||
|
- **Booster Cooldown** - Time until boosters can be used
|
||||||
|
|
||||||
|
Timers count down in real-time and notify you when ready.
|
||||||
|
|
||||||
|
### Status Badges
|
||||||
|
|
||||||
|
Visual indicators for special states:
|
||||||
|
- **Hospital** - Red badge when hospitalized
|
||||||
|
- **Jail** - Gray badge when in jail
|
||||||
|
- **Messages** - Badge showing unread message count
|
||||||
|
|
||||||
|
### Chain Timer
|
||||||
|
|
||||||
|
When your faction has an active chain:
|
||||||
|
- Displays current chain count
|
||||||
|
- Shows timeout timer
|
||||||
|
- Warns when chain is about to expire
|
||||||
|
|
||||||
|
### Events Feed
|
||||||
|
|
||||||
|
Recent events scroll showing:
|
||||||
|
- Incoming attacks
|
||||||
|
- Messages received
|
||||||
|
- Money transfers
|
||||||
|
- Other significant events
|
||||||
|
|
||||||
|
### Quick Links
|
||||||
|
|
||||||
|
8 customizable quick-access buttons:
|
||||||
|
- Gym, Items, Properties
|
||||||
|
- Missions, Crimes, Jail
|
||||||
|
- Hospital, Casino
|
||||||
|
|
||||||
|
## Travel Tab
|
||||||
|
|
||||||
|
Comprehensive travel management with live tracking.
|
||||||
|
|
||||||
|
### Travel Status
|
||||||
|
|
||||||
|
Three possible states displayed:
|
||||||
|
|
||||||
|
**In Torn City**
|
||||||
|
- Home icon with "Ready to travel" message
|
||||||
|
- Access to destination picker
|
||||||
|
|
||||||
|
**Flying**
|
||||||
|
- Live countdown timer updating every second
|
||||||
|
- Destination with country flag
|
||||||
|
- Progress bar showing flight completion
|
||||||
|
- Menu bar displays: ✈️🇬🇧 5:32 (airplane + flag + time)
|
||||||
|
|
||||||
|
**Abroad**
|
||||||
|
- Globe icon showing current location
|
||||||
|
- "Return to Torn" button for quick return
|
||||||
|
|
||||||
|
### Destination Picker
|
||||||
|
|
||||||
|
Quick travel buttons for all 11 Torn destinations:
|
||||||
|
|
||||||
|
| Destination | Flag | Flight Time |
|
||||||
|
|-------------|------|-------------|
|
||||||
|
| Mexico | 🇲🇽 | ~26 min |
|
||||||
|
| Cayman Islands | 🇰🇾 | ~35 min |
|
||||||
|
| Canada | 🇨🇦 | ~41 min |
|
||||||
|
| Hawaii | 🇺🇸 | ~2h 14m |
|
||||||
|
| United Kingdom | 🇬🇧 | ~2h 31m |
|
||||||
|
| Argentina | 🇦🇷 | ~2h 45m |
|
||||||
|
| Switzerland | 🇨🇭 | ~2h 50m |
|
||||||
|
| Japan | 🇯🇵 | ~3h 30m |
|
||||||
|
| China | 🇨🇳 | ~3h 52m |
|
||||||
|
| UAE | 🇦🇪 | ~4h 22m |
|
||||||
|
| South Africa | 🇿🇦 | ~4h 45m |
|
||||||
|
|
||||||
|
Click any destination to open Torn's travel agency with that destination selected.
|
||||||
|
|
||||||
|
### Pre-Arrival Alerts
|
||||||
|
|
||||||
|
Configurable notifications before landing:
|
||||||
|
- **2 minutes** before arrival
|
||||||
|
- **1 minute** before arrival
|
||||||
|
- **30 seconds** before arrival
|
||||||
|
- **10 seconds** before arrival
|
||||||
|
|
||||||
|
Enable/disable each interval independently.
|
||||||
|
|
||||||
|
## Money Tab
|
||||||
|
|
||||||
|
Financial overview and quick actions.
|
||||||
|
|
||||||
|
### Balance Display
|
||||||
|
|
||||||
|
- **Cash on Hand** - Your pocket money
|
||||||
|
- **Vault** - Bank vault balance
|
||||||
|
- **Points** - Current points
|
||||||
|
- **Tokens** - Job tokens
|
||||||
|
|
||||||
|
### Quick Actions
|
||||||
|
|
||||||
|
- **Send Money** - Opens money transfer page
|
||||||
|
- **Bazaar** - Opens your bazaar
|
||||||
|
- **Bank** - Opens Torn bank
|
||||||
|
|
||||||
|
## Attacks Tab
|
||||||
|
|
||||||
|
Combat statistics and history.
|
||||||
|
|
||||||
|
### Battle Stats
|
||||||
|
|
||||||
|
Your four battle statistics:
|
||||||
|
- **Strength**
|
||||||
|
- **Defense**
|
||||||
|
- **Speed**
|
||||||
|
- **Dexterity**
|
||||||
|
|
||||||
|
### Recent Attacks
|
||||||
|
|
||||||
|
List of recent attack results showing:
|
||||||
|
- Target name
|
||||||
|
- Win/Loss outcome
|
||||||
|
- Timestamp
|
||||||
|
|
||||||
|
### Quick Actions
|
||||||
|
|
||||||
|
- **Attack** - Opens attack page
|
||||||
|
- **Hospital** - Opens hospital list
|
||||||
|
- **Bounties** - Opens bounty list
|
||||||
|
|
||||||
|
## Faction Tab
|
||||||
|
|
||||||
|
Faction information and utilities.
|
||||||
|
|
||||||
|
### Faction Info
|
||||||
|
|
||||||
|
- Faction name and ID
|
||||||
|
- Your position/rank
|
||||||
|
- Member count
|
||||||
|
|
||||||
|
### Chain Status
|
||||||
|
|
||||||
|
When chain is active:
|
||||||
|
- Current chain count
|
||||||
|
- Time to timeout
|
||||||
|
- Visual warning when expiring
|
||||||
|
|
||||||
|
### War Status
|
||||||
|
|
||||||
|
If faction is at war:
|
||||||
|
- War opponent
|
||||||
|
- War score
|
||||||
|
- Territory control
|
||||||
|
|
||||||
|
### Armory Quick-Use
|
||||||
|
|
||||||
|
Buttons for common armory items (if available).
|
||||||
|
|
||||||
|
## Watchlist Tab
|
||||||
|
|
||||||
|
Track item market prices in real-time using Torn API v2.
|
||||||
|
|
||||||
|
### Price Tracking
|
||||||
|
|
||||||
|
For each watched item shows:
|
||||||
|
- Item name with market link
|
||||||
|
- **Lowest price** on Item Market
|
||||||
|
- **Quantity** at lowest price (e.g., "$4.2M x12")
|
||||||
|
- Price change indicator (if price increased)
|
||||||
|
|
||||||
|
### Adding Items
|
||||||
|
|
||||||
|
Click the **+** button to add items from a preset list:
|
||||||
|
- Xanax
|
||||||
|
- FHC (Feathery Hotel Coupon)
|
||||||
|
- Donator Pack
|
||||||
|
- Drug Pack
|
||||||
|
- Energy Drink
|
||||||
|
- First Aid Kit
|
||||||
|
|
||||||
|
### Market Links
|
||||||
|
|
||||||
|
Quick access to:
|
||||||
|
- Item Market
|
||||||
|
- Points Market
|
||||||
|
|
||||||
|
## Settings Tab
|
||||||
|
|
||||||
|
Configure MacTorn to your preferences.
|
||||||
|
|
||||||
|
### API Key Management
|
||||||
|
|
||||||
|
- Secure input field for API key
|
||||||
|
- "Save & Connect" to apply key
|
||||||
|
- Link to generate new key on Torn
|
||||||
|
|
||||||
|
### Refresh Interval
|
||||||
|
|
||||||
|
Choose polling frequency:
|
||||||
|
- 15 seconds
|
||||||
|
- 30 seconds (default)
|
||||||
|
- 60 seconds
|
||||||
|
- 2 minutes
|
||||||
|
|
||||||
|
### Appearance
|
||||||
|
|
||||||
|
- **System** - Follow macOS appearance
|
||||||
|
- **Light** - Always light mode
|
||||||
|
- **Dark** - Always dark mode
|
||||||
|
|
||||||
|
### Accessibility
|
||||||
|
|
||||||
|
- **Reduce Transparency** - Use solid backgrounds for better readability
|
||||||
|
|
||||||
|
### Launch at Login
|
||||||
|
|
||||||
|
Toggle to start MacTorn automatically when you log into your Mac.
|
||||||
|
|
||||||
|
### Update Notifications
|
||||||
|
|
||||||
|
When a new version is available:
|
||||||
|
- Version number displayed
|
||||||
|
- "Download Update" button links to GitHub releases
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next:** [[Configuration]] - Detailed configuration options
|
||||||
91
wiki/Getting-Started.md
Normal file
91
wiki/Getting-Started.md
Normal file
|
|
@ -0,0 +1,91 @@
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
This guide will help you set up MacTorn and understand its basic features.
|
||||||
|
|
||||||
|
## Step 1: Get Your Torn API Key
|
||||||
|
|
||||||
|
To use MacTorn, you need a Torn API key. See [[API-Setup]] for detailed instructions, or follow these quick steps:
|
||||||
|
|
||||||
|
1. Log into [Torn](https://www.torn.com)
|
||||||
|
2. Go to **Settings** > **API Keys** or directly visit: https://www.torn.com/preferences.php#tab=api
|
||||||
|
3. Create a new key with **Full Access** or select the required permissions
|
||||||
|
4. Copy the generated 16-character key
|
||||||
|
|
||||||
|
## Step 2: Configure MacTorn
|
||||||
|
|
||||||
|
1. Click the MacTorn icon in your menu bar (bolt icon)
|
||||||
|
2. Navigate to the **Settings** tab (gear icon)
|
||||||
|
3. Paste your API key in the **Torn API Key** field
|
||||||
|
4. Click **Save & Connect**
|
||||||
|
|
||||||
|
MacTorn will immediately start fetching your Torn data.
|
||||||
|
|
||||||
|
## Understanding the Menu Bar Icon
|
||||||
|
|
||||||
|
The menu bar icon changes based on your status:
|
||||||
|
|
||||||
|
| Icon | Status |
|
||||||
|
|------|--------|
|
||||||
|
| Bolt outline | Normal (energy not full) |
|
||||||
|
| Bolt filled | Energy is full |
|
||||||
|
| Globe | Currently abroad |
|
||||||
|
| Warning triangle | Error (API issue) |
|
||||||
|
| Airplane + flag + timer | Currently traveling (e.g., "✈️🇬🇧 5:32") |
|
||||||
|
|
||||||
|
## Basic Navigation
|
||||||
|
|
||||||
|
MacTorn organizes information into tabs. Click the menu bar icon to open the window, then use the tab bar at the bottom:
|
||||||
|
|
||||||
|
### Tab Overview
|
||||||
|
|
||||||
|
| Tab | Icon | Purpose |
|
||||||
|
|-----|------|---------|
|
||||||
|
| **Status** | Bolt | Energy, Nerve, Happy, Life bars, cooldowns, events |
|
||||||
|
| **Travel** | Airplane | Travel status, destination picker, pre-arrival alerts |
|
||||||
|
| **Money** | Dollar | Cash, vault, points, tokens, quick actions |
|
||||||
|
| **Attacks** | Crosshairs | Battle stats, recent attacks |
|
||||||
|
| **Faction** | Building | Faction info, chain status, war status |
|
||||||
|
| **Watchlist** | Chart | Item price tracking |
|
||||||
|
| **Settings** | Gear | API key, refresh interval, appearance |
|
||||||
|
|
||||||
|
## Using Quick Links
|
||||||
|
|
||||||
|
The Status tab includes 8 customizable quick links for fast access to common Torn pages:
|
||||||
|
|
||||||
|
- Gym, Items, Properties
|
||||||
|
- Missions, Crimes, Jail
|
||||||
|
- Hospital, Casino
|
||||||
|
|
||||||
|
Click any quick link to open that page in your default browser.
|
||||||
|
|
||||||
|
## Notifications
|
||||||
|
|
||||||
|
MacTorn can send macOS notifications for important events:
|
||||||
|
|
||||||
|
- Energy/Nerve thresholds reached
|
||||||
|
- Cooldowns ready
|
||||||
|
- Travel landing
|
||||||
|
- Chain expiring
|
||||||
|
- Hospital/Jail release
|
||||||
|
|
||||||
|
Configure notification rules in the Settings tab or see [[Configuration]] for details.
|
||||||
|
|
||||||
|
## Refresh Interval
|
||||||
|
|
||||||
|
By default, MacTorn fetches data every 30 seconds. You can change this in Settings:
|
||||||
|
|
||||||
|
- **15s** - Most frequent updates
|
||||||
|
- **30s** - Balanced (default)
|
||||||
|
- **60s** - Less frequent
|
||||||
|
- **2m** - Minimal API usage
|
||||||
|
|
||||||
|
## Tips for New Users
|
||||||
|
|
||||||
|
1. **Enable Launch at Login** - Find this in Settings to have MacTorn start with your Mac
|
||||||
|
2. **Set up Watchlist** - Track item prices you care about in the Watchlist tab
|
||||||
|
3. **Configure Travel Alerts** - Enable pre-arrival notifications in the Travel tab so you don't miss your landing
|
||||||
|
4. **Check Events** - The Status tab shows recent events so you don't miss attacks or messages
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next:** [[Features]] - Explore all features in detail
|
||||||
49
wiki/Home.md
Normal file
49
wiki/Home.md
Normal file
|
|
@ -0,0 +1,49 @@
|
||||||
|
# MacTorn Wiki
|
||||||
|
|
||||||
|
Welcome to the MacTorn wiki! MacTorn is a native macOS menu bar app for monitoring your [Torn](https://www.torn.com) game status.
|
||||||
|
|
||||||
|
## What is MacTorn?
|
||||||
|
|
||||||
|
MacTorn sits in your menu bar and provides real-time monitoring of your Torn player status without needing to keep a browser tab open. It displays energy bars, travel timers, chain status, and more - all accessible with a single click.
|
||||||
|
|
||||||
|
## Quick Links
|
||||||
|
|
||||||
|
- [[Installation]] - Get MacTorn up and running
|
||||||
|
- [[Getting-Started]] - Configure your API key and start using MacTorn
|
||||||
|
- [[Features]] - Explore all features in detail
|
||||||
|
- [[Configuration]] - Customize settings to your preference
|
||||||
|
- [[FAQ]] - Common questions answered
|
||||||
|
- [[Troubleshooting]] - Solutions to common issues
|
||||||
|
|
||||||
|
## Feature Highlights
|
||||||
|
|
||||||
|
- **Live Status Bars** - Energy, Nerve, Happy, Life with color-coded progress
|
||||||
|
- **Travel Monitoring** - Live countdown in menu bar with pre-arrival notifications
|
||||||
|
- **Chain Timer** - Never miss a chain timeout
|
||||||
|
- **Item Watchlist** - Track market prices in real-time
|
||||||
|
- **Smart Notifications** - Customizable alerts for important events
|
||||||
|
- **Accessibility Support** - Respects macOS accessibility settings
|
||||||
|
|
||||||
|
## Current Version
|
||||||
|
|
||||||
|
**v1.4.4** - See [[Changelog]] for release history.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- macOS 13.0 (Ventura) or later
|
||||||
|
- Universal Binary: Supports Intel (x86_64) and Apple Silicon (arm64)
|
||||||
|
- Torn API Key
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
- Check the [[FAQ]] for common questions
|
||||||
|
- See [[Troubleshooting]] for solutions to issues
|
||||||
|
- Report bugs on [GitHub Issues](https://github.com/pawelorzech/MacTorn/issues)
|
||||||
|
|
||||||
|
## Support the Developer
|
||||||
|
|
||||||
|
If you find MacTorn useful, consider sending some Xanax or cash to **bombel** [[2362436](https://www.torn.com/profiles.php?XID=2362436)]!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Made for the Torn community
|
||||||
76
wiki/Installation.md
Normal file
76
wiki/Installation.md
Normal file
|
|
@ -0,0 +1,76 @@
|
||||||
|
# Installation
|
||||||
|
|
||||||
|
This guide covers how to install MacTorn on your Mac.
|
||||||
|
|
||||||
|
## System Requirements
|
||||||
|
|
||||||
|
| Requirement | Details |
|
||||||
|
|-------------|---------|
|
||||||
|
| **macOS Version** | 13.0 (Ventura) or later |
|
||||||
|
| **Architecture** | Universal Binary - Intel (x86_64) and Apple Silicon (arm64) |
|
||||||
|
| **Storage** | ~10 MB |
|
||||||
|
| **Network** | Internet connection for Torn API |
|
||||||
|
|
||||||
|
## Download
|
||||||
|
|
||||||
|
1. Visit the [Releases page](https://github.com/pawelorzech/MacTorn/releases)
|
||||||
|
2. Download the latest `MacTorn.zip` file
|
||||||
|
3. Unzip the downloaded file
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
1. Drag `MacTorn.app` to your **Applications** folder
|
||||||
|
2. Open MacTorn from Applications (or Spotlight search)
|
||||||
|
|
||||||
|
## Gatekeeper Warning (Unsigned App)
|
||||||
|
|
||||||
|
Since MacTorn is not signed with an Apple Developer certificate, macOS Gatekeeper will block it on first launch. Here's how to bypass this:
|
||||||
|
|
||||||
|
### Method 1: Right-Click Open
|
||||||
|
|
||||||
|
1. **Right-click** (or Control-click) on `MacTorn.app`
|
||||||
|
2. Select **Open** from the context menu
|
||||||
|
3. Click **Open** in the dialog that appears
|
||||||
|
|
||||||
|
### Method 2: System Settings
|
||||||
|
|
||||||
|
1. Try to open MacTorn normally (it will be blocked)
|
||||||
|
2. Open **System Settings** (or System Preferences on older macOS)
|
||||||
|
3. Go to **Privacy & Security**
|
||||||
|
4. Scroll down to the Security section
|
||||||
|
5. You'll see a message about MacTorn being blocked
|
||||||
|
6. Click **Open Anyway**
|
||||||
|
7. Enter your password if prompted
|
||||||
|
8. Click **Open** in the confirmation dialog
|
||||||
|
|
||||||
|
## First Launch
|
||||||
|
|
||||||
|
After successfully opening MacTorn:
|
||||||
|
|
||||||
|
1. The app will appear as a bolt icon in your menu bar
|
||||||
|
2. Click the icon to open the MacTorn window
|
||||||
|
3. Navigate to the **Settings** tab
|
||||||
|
4. Enter your Torn API Key (see [[API-Setup]])
|
||||||
|
5. Click **Save & Connect**
|
||||||
|
|
||||||
|
## Updating MacTorn
|
||||||
|
|
||||||
|
MacTorn automatically checks for updates. When a new version is available:
|
||||||
|
|
||||||
|
1. A notification appears in the Settings tab
|
||||||
|
2. Click **Download Update** to open the releases page
|
||||||
|
3. Download and replace the old version with the new one
|
||||||
|
|
||||||
|
Alternatively, manually check [GitHub Releases](https://github.com/pawelorzech/MacTorn/releases) for new versions.
|
||||||
|
|
||||||
|
## Uninstalling
|
||||||
|
|
||||||
|
To remove MacTorn:
|
||||||
|
|
||||||
|
1. Quit MacTorn if running (right-click menu bar icon)
|
||||||
|
2. Delete `MacTorn.app` from Applications
|
||||||
|
3. (Optional) Remove preferences: delete `~/Library/Preferences/com.bombel.MacTorn.plist`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next:** [[Getting-Started]] - Configure your API key
|
||||||
194
wiki/Troubleshooting.md
Normal file
194
wiki/Troubleshooting.md
Normal file
|
|
@ -0,0 +1,194 @@
|
||||||
|
# Troubleshooting
|
||||||
|
|
||||||
|
This page covers common issues and their solutions.
|
||||||
|
|
||||||
|
## Can't Open MacTorn (Gatekeeper)
|
||||||
|
|
||||||
|
**Symptom:** "MacTorn can't be opened because it is from an unidentified developer"
|
||||||
|
|
||||||
|
**Cause:** macOS Gatekeeper blocks unsigned applications.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
|
||||||
|
**Method 1 - Right-Click Open:**
|
||||||
|
1. Right-click (or Control-click) on MacTorn.app
|
||||||
|
2. Select "Open" from the menu
|
||||||
|
3. Click "Open" in the dialog
|
||||||
|
|
||||||
|
**Method 2 - System Settings:**
|
||||||
|
1. Try opening MacTorn (it will be blocked)
|
||||||
|
2. Go to System Settings > Privacy & Security
|
||||||
|
3. Scroll to find the message about MacTorn
|
||||||
|
4. Click "Open Anyway"
|
||||||
|
5. Enter your password and click "Open"
|
||||||
|
|
||||||
|
## API Key Errors
|
||||||
|
|
||||||
|
### "Invalid API Key"
|
||||||
|
|
||||||
|
**Cause:** The key you entered is incorrect or has been revoked.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Go to https://www.torn.com/preferences.php#tab=api
|
||||||
|
2. Verify your key exists and matches what you entered
|
||||||
|
3. If in doubt, create a new key
|
||||||
|
4. Copy the key carefully (16 characters)
|
||||||
|
5. Re-enter in MacTorn Settings
|
||||||
|
|
||||||
|
### "Insufficient Permissions"
|
||||||
|
|
||||||
|
**Cause:** Your API key doesn't have the required permissions.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Create a new API key with "Full Access"
|
||||||
|
2. Or select these specific permissions:
|
||||||
|
- basic, bars, cooldowns, travel, profile, events, messages, money, battlestats, attacks
|
||||||
|
|
||||||
|
### "API Request Failed"
|
||||||
|
|
||||||
|
**Cause:** Network issue or Torn API is down.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Check your internet connection
|
||||||
|
2. Try visiting https://www.torn.com to verify Torn is accessible
|
||||||
|
3. Wait and try again - Torn API occasionally has downtime
|
||||||
|
4. Click "Refresh" or wait for next automatic refresh
|
||||||
|
|
||||||
|
## Menu Bar Icon Issues
|
||||||
|
|
||||||
|
### Icon Not Appearing
|
||||||
|
|
||||||
|
**Cause:** MacTorn may not have launched properly.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Check if MacTorn is running (Activity Monitor)
|
||||||
|
2. Quit and relaunch MacTorn
|
||||||
|
3. Check System Settings > Control Center > Menu Bar Only to ensure there's space
|
||||||
|
|
||||||
|
### Wrong Icon Displayed
|
||||||
|
|
||||||
|
**Cause:** Normal behavior - icon changes based on status.
|
||||||
|
|
||||||
|
**Reference:**
|
||||||
|
- Bolt outline = Normal
|
||||||
|
- Bolt filled = Energy full
|
||||||
|
- Globe = Abroad
|
||||||
|
- Triangle = Error
|
||||||
|
- Airplane + timer = Traveling
|
||||||
|
|
||||||
|
## Notifications Not Working
|
||||||
|
|
||||||
|
### No Notifications Appear
|
||||||
|
|
||||||
|
**Cause:** macOS notification permissions.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Open System Settings > Notifications
|
||||||
|
2. Find MacTorn in the list
|
||||||
|
3. Ensure "Allow Notifications" is ON
|
||||||
|
4. Set alert style to "Banners" or "Alerts"
|
||||||
|
|
||||||
|
### Notification Sound Missing
|
||||||
|
|
||||||
|
**Cause:** Sound disabled in notification settings.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. System Settings > Notifications > MacTorn
|
||||||
|
2. Enable "Play sound for notifications"
|
||||||
|
|
||||||
|
### Travel Alerts Not Working
|
||||||
|
|
||||||
|
**Cause:** Pre-arrival alerts may be disabled.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Open MacTorn > Travel tab
|
||||||
|
2. Under "Pre-Arrival Alerts"
|
||||||
|
3. Enable the time intervals you want
|
||||||
|
|
||||||
|
## Data Not Updating
|
||||||
|
|
||||||
|
### Bars/Stats Stuck
|
||||||
|
|
||||||
|
**Cause:** Polling may have stopped or API error.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Check the menu bar icon - triangle means error
|
||||||
|
2. Go to Settings and verify API key
|
||||||
|
3. Try changing refresh interval (triggers restart)
|
||||||
|
4. Quit and relaunch MacTorn
|
||||||
|
|
||||||
|
### Watchlist Prices Not Loading
|
||||||
|
|
||||||
|
**Cause:** API v2 permissions or item ID issues.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Ensure your API key has market access
|
||||||
|
2. Click the refresh button in Watchlist tab
|
||||||
|
3. Remove and re-add items
|
||||||
|
|
||||||
|
## Performance Issues
|
||||||
|
|
||||||
|
### High CPU Usage
|
||||||
|
|
||||||
|
**Cause:** Rare, possibly rendering loop.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Quit and relaunch MacTorn
|
||||||
|
2. Try a longer refresh interval (60s or 2m)
|
||||||
|
3. If persists, file a bug report
|
||||||
|
|
||||||
|
### App Feels Slow
|
||||||
|
|
||||||
|
**Cause:** Normal behavior during initial load.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
- MacTorn uses non-blocking data fetching
|
||||||
|
- UI should remain responsive
|
||||||
|
- First load may show empty data briefly
|
||||||
|
|
||||||
|
## Window Issues
|
||||||
|
|
||||||
|
### Window Won't Open
|
||||||
|
|
||||||
|
**Cause:** Window may be off-screen.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Quit MacTorn
|
||||||
|
2. Run in Terminal: `defaults delete com.bombel.MacTorn`
|
||||||
|
3. Relaunch MacTorn
|
||||||
|
|
||||||
|
### Window Too Small/Cut Off
|
||||||
|
|
||||||
|
**Cause:** Display scaling issues.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Try different appearance mode in Settings
|
||||||
|
2. Quit and relaunch
|
||||||
|
|
||||||
|
## Update Issues
|
||||||
|
|
||||||
|
### "New Version Available" but Can't Update
|
||||||
|
|
||||||
|
**Cause:** Manual update required.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Click "Download Update" in Settings
|
||||||
|
2. Download the new version from GitHub
|
||||||
|
3. Quit MacTorn
|
||||||
|
4. Replace old .app with new one
|
||||||
|
5. Relaunch (may need Gatekeeper bypass again)
|
||||||
|
|
||||||
|
## Reporting Bugs
|
||||||
|
|
||||||
|
If your issue isn't listed here:
|
||||||
|
|
||||||
|
1. **Check GitHub Issues** - https://github.com/pawelorzech/MacTorn/issues
|
||||||
|
2. **Create New Issue** with:
|
||||||
|
- macOS version
|
||||||
|
- MacTorn version (found in Settings)
|
||||||
|
- Steps to reproduce
|
||||||
|
- Screenshots if applicable
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**See Also:** [[FAQ]] for common questions
|
||||||
28
wiki/_Sidebar.md
Normal file
28
wiki/_Sidebar.md
Normal file
|
|
@ -0,0 +1,28 @@
|
||||||
|
# MacTorn Wiki
|
||||||
|
|
||||||
|
**[[Home]]**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Getting Started
|
||||||
|
- [[Installation]]
|
||||||
|
- [[Getting-Started]]
|
||||||
|
- [[API-Setup]]
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
- [[Features]]
|
||||||
|
- [[Configuration]]
|
||||||
|
|
||||||
|
### Help
|
||||||
|
- [[Troubleshooting]]
|
||||||
|
- [[FAQ]]
|
||||||
|
|
||||||
|
### Development
|
||||||
|
- [[Development]]
|
||||||
|
- [[Changelog]]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[GitHub Repository](https://github.com/pawelorzech/MacTorn)
|
||||||
|
|
||||||
|
[Report Issue](https://github.com/pawelorzech/MacTorn/issues)
|
||||||
Loading…
Reference in a new issue