pawel/MacTorn
1
0
Fork 0
mirror of https://github.com/pawelorzech/MacTorn.git synced 2026-01-29 19:54:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Add comprehensive GitHub wiki documentation

Browse source 
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 2026-01-20 13:24:55 +00:00
parent e10add9474
commit 715f0877ff
No known key found for this signature in database
11 changed files with 1504 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

139
wiki/API-Setup.md Normal file
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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)