From a2d3e6416f12ec0397174372b24d22ffe3ffb734 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Orzech?= Date: Tue, 20 Jan 2026 13:30:20 +0000 Subject: [PATCH] docs: Migrate wiki to GitHub Wiki feature Move documentation from wiki/ folder to GitHub Wiki repository. Add wiki link to README for easy access. --- README.md | 4 + wiki/API-Setup.md | 139 ---------------------- wiki/Changelog.md | 133 --------------------- wiki/Configuration.md | 167 -------------------------- wiki/Development.md | 250 --------------------------------------- wiki/FAQ.md | 124 -------------------- wiki/Features.md | 253 ---------------------------------------- wiki/Getting-Started.md | 91 --------------- wiki/Home.md | 49 -------- wiki/Installation.md | 76 ------------ wiki/Troubleshooting.md | 194 ------------------------------ wiki/_Sidebar.md | 28 ----- 12 files changed, 4 insertions(+), 1504 deletions(-) delete mode 100644 wiki/API-Setup.md delete mode 100644 wiki/Changelog.md delete mode 100644 wiki/Configuration.md delete mode 100644 wiki/Development.md delete mode 100644 wiki/FAQ.md delete mode 100644 wiki/Features.md delete mode 100644 wiki/Getting-Started.md delete mode 100644 wiki/Home.md delete mode 100644 wiki/Installation.md delete mode 100644 wiki/Troubleshooting.md delete mode 100644 wiki/_Sidebar.md diff --git a/README.md b/README.md index 37a3263..c2f69f1 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,10 @@ A native macOS menu bar app for monitoring your **Torn** game status. MacTorn Dark Mode

+## Documentation + +For detailed documentation, visit the [MacTorn Wiki](https://github.com/pawelorzech/MacTorn/wiki). + ## Features ### πŸ“Š Status Tab diff --git a/wiki/API-Setup.md b/wiki/API-Setup.md deleted file mode 100644 index 498a695..0000000 --- a/wiki/API-Setup.md +++ /dev/null @@ -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 diff --git a/wiki/Changelog.md b/wiki/Changelog.md deleted file mode 100644 index 780a5a8..0000000 --- a/wiki/Changelog.md +++ /dev/null @@ -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). diff --git a/wiki/Configuration.md b/wiki/Configuration.md deleted file mode 100644 index ed44c91..0000000 --- a/wiki/Configuration.md +++ /dev/null @@ -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 diff --git a/wiki/Development.md b/wiki/Development.md deleted file mode 100644 index 14f29d2..0000000 --- a/wiki/Development.md +++ /dev/null @@ -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 diff --git a/wiki/FAQ.md b/wiki/FAQ.md deleted file mode 100644 index 306efcd..0000000 --- a/wiki/FAQ.md +++ /dev/null @@ -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 diff --git a/wiki/Features.md b/wiki/Features.md deleted file mode 100644 index 4907e16..0000000 --- a/wiki/Features.md +++ /dev/null @@ -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 diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md deleted file mode 100644 index 1e6a640..0000000 --- a/wiki/Getting-Started.md +++ /dev/null @@ -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 diff --git a/wiki/Home.md b/wiki/Home.md deleted file mode 100644 index 499a3bc..0000000 --- a/wiki/Home.md +++ /dev/null @@ -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 diff --git a/wiki/Installation.md b/wiki/Installation.md deleted file mode 100644 index a2f3d02..0000000 --- a/wiki/Installation.md +++ /dev/null @@ -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 diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md deleted file mode 100644 index f23f82c..0000000 --- a/wiki/Troubleshooting.md +++ /dev/null @@ -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 diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md deleted file mode 100644 index 297da5d..0000000 --- a/wiki/_Sidebar.md +++ /dev/null @@ -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)