mirror of
https://github.com/pawelorzech/MacTorn.git
synced 2026-01-30 04:04:27 +00:00
docs: Migrate wiki to GitHub Wiki feature
Move documentation from wiki/ folder to GitHub Wiki repository. Add wiki link to README for easy access.
This commit is contained in:
Paweł Orzech
parent
715f0877ff
commit
a2d3e6416f
12 changed files with 4 additions and 1504 deletions
|
|
@ -13,6 +13,10 @@ A native macOS menu bar app for monitoring your **Torn** game status.
|
|||
<img src="app_dark_1.png" alt="MacTorn Dark Mode" width="320">
|
||||
</p>
|
||||
|
||||
## Documentation
|
||||
|
||||
For detailed documentation, visit the [MacTorn Wiki](https://github.com/pawelorzech/MacTorn/wiki).
|
||||
|
||||
## Features
|
||||
|
||||
### 📊 Status Tab
|
||||
|
|
|
|||
|
|
@ -1,139 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,133 +0,0 @@
|
|||
# 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).
|
||||
|
|
@ -1,167 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,250 +0,0 @@
|
|||
# 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
124
wiki/FAQ.md
|
|
@ -1,124 +0,0 @@
|
|||
# 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
253
wiki/Features.md
|
|
@ -1,253 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,91 +0,0 @@
|
|||
# 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
49
wiki/Home.md
|
|
@ -1,49 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,76 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,194 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
# 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