maplestory 1.3.3 - macOS Quick Setup Guide
=================================================

Product guide:
https://maple.okya.app/en/maplestory-classic-world-bot

1. Start the application
------------------------
- Choose the package that matches your Mac. Apple menu > About This Mac shows its chip or processor:
  - Apple Silicon (M series): use macos-arm64.zip; requires macOS 11 or newer.
  - Intel processor: use macos-x86_64.zip; requires macOS 12 or newer.
- Extract the entire ZIP archive before running the application. Both packages contain the same app name.
- Copy "maplestory.app" to Applications, then open it from that location. If an older "okay for MapleStory.app" is there, delete it; your license and settings are kept.
- Allow that app in System Settings > Privacy & Security > Accessibility and Screen & System Audio Recording.
  Older macOS versions call these System Preferences > Security & Privacy and Screen Recording.
- Restart the app after granting permissions. Screen-capture selection is not a replacement for these permissions.
- In Basic > Window source > Choose window, select the actual game preview and confirm.
- Select again after restarting the game; the app never guesses a window by title or captures the whole display as a fallback.
- Keep the MapleStory game window open and in the foreground while automation is running.
- Complete license activation before using the combat features.

2. Supported game resolution
----------------------------
- Set the resolution INSIDE THE GAME to 1366 x 768 and use windowed mode or borderless fullscreen.
- Select the same 1366 x 768 resolution in the app's Basic tab. This setting does not resize the game.
- After changing game resolution, stop the current run and click Start again. Choose the game window again if it changed.
- Other resolutions may cause incorrect character, monster, minimap, HP, or MP detection.

3. Character templates
----------------------
- Open the character list and use the + button to add a character.
- Enter a unique character name.
- Capture the character facing left first, then facing right.
- Keep the character's appearance unchanged between both captures.
- Place the character in the same position inside both capture boxes.
- Capture only the character sprite. Do not include platforms, scenery, text, effects, other characters, or monsters.
- Use a clear frame without attack, damage, skill, or movement effects.
- Template selection covers the multi-display desktop. Select only the game sprite; runtime recognition still uses the chosen game window.
- New character captures use a fixed 15 x 15 px feature box. Existing 20 x 20 templates remain supported.
- After both captures, click Save and use to create and select the character; closing the panel discards unsaved captures.

4. Monster templates
--------------------
- Open the monster list and use the + button to add a monster.
- Capture the same monster facing left and facing right.
- Keep the monster in the same position inside both capture boxes.
- Capture only the monster sprite and avoid all background pixels, platforms, names, damage numbers, and visual effects.
- Use a stable idle frame whenever possible.
- After both captures, click Save and use. Monster selections save automatically; closing a template panel discards unsaved captures.
- Select only the monsters that appear on the current map. Selecting too many templates reduces detection performance.

5. Combat settings
------------------
- Skills: Combat has up to 4 skill tabs. Each skill has its own enabled switch (all off by default), key (unbound by default), trigger monster count (1, 2, 3, 4 by default), front, back and vertical range, and range drawing.
- A skill is used when the monsters inside its own range reach its trigger count. When several qualify, the highest trigger count wins; ties go to the lower skill number.
- At least one enabled skill with a key is required to start. Enabling a skill, buff, pickup or auto HP/MP without a key is refused with a prompt.
- Jump key: in Basic, below Movement keys. Unbound by default and required to start; it must match the key assigned inside MapleStory.
- macOS cannot send modifier keys, F11/F12 or Insert. Such keys, and duplicate keys, are cleared from older settings on load with a notice.
- Basic > Movement keys: choose Arrow keys (default) or WASD to match the game's movement bindings. WASD sends W/A/S/D for up/left/down/right, including ladders and portals. Skill and jump keys keep their own configured bindings.
- Stop and start again after changing movement keys. The selection is saved automatically.
- Front range (px): reach in the attack direction, default 125 (minimum 80). Back range: reach behind, default 0. Vertical range: default 75 (minimum 50).
- Values below the minimum are reported and the last valid value is kept. Blank/nonnumeric edits keep the last valid settings. Start/Close flush pending edits.
- Skill ranges are drawn as blue, green, purple and pink dashed boxes labeled with the skill number. Players are yellow and monsters red solid boxes.
- Attack checks and range drawing use the body center, 30px above the original detected feet coordinate; navigation and minimap coordinates are unchanged.
- The retired maximum chase distance is ignored. Preset-route combat uses the largest front and vertical range of the enabled skills.
- Start with conservative ranges and adjust them for the selected character, skill, and map.
- A larger range value does not extend the weapon's or skill's actual reach. Configure only skills the character has learned.
- Valid setting changes save automatically after a short delay. Incomplete or invalid edits keep the last valid settings.
- Stop the current run and click Start again after changing combat settings. Saving does not reconfigure an active run.
- Theme and language changes apply after restarting the application.

6. Combat modes and minimap
---------------------------
- Stationary Attack offers automatic direction adjustment (default on) and automatic return to origin (default on, can be disabled).
- Infinite attack (default off) skips monster matching in full-operation mode and continuously applies the key of the enabled skill with the lowest trigger count in the current facing. Skill switching and monster-based turning are bypassed. Valid capture/player/minimap tracking and game focus are still required.
- Stationary attacks reassert held input every 150ms on fresh observations. Due pickups release attack first, then the next valid decision resumes it. Normal mode stops attacking when no actionable targets remain.
- Optional anti-idle movement (default off): every 60 seconds, release attack, wait 1 second, then hold the opposite and original directions for 0.25 seconds each; restore facing and prior attack. Old anti-idle jump settings migrate; no scheduled jump is sent.
- Two-Point Patrol moves between the configured A and B horizontal coordinates.
- Combat is permitted throughout the interval; targets outside A minus / B plus the largest enabled front range are ignored using 16 client pixels per minimap pixel. At endpoints, only targets already in hit range are attacked.
- A successfully issued attack has a fixed 0.30s startup window against brief misses/jitter; the optional attack-duration setting holds attack for a 1s tail before changing action. Position loss, leaving patrol bounds, stale capture, Stop and alarms still release input.
- Two-point attacks reassert key-down every 150ms on fresh observations, independently of tail protection. Recovering player recognition does not insert a key-up. A returning target does not restart the startup/tail deadlines of the same held attack. Pickups wait while attacking. Old endpoints-only and stationary-duration-protection options are removed on the next save.
- Knockback beyond A/B by more than the 2px minimap tolerance prioritizes returning inward over attacking nearby targets. Attacks within the endpoint tolerance remain allowed.
- Preset Route Patrol follows the selected route map.
- Make sure the in-game minimap is visible and unobstructed before pressing Start.
- Starting combat performs a fresh character and minimap check. Combat will not start if either required check fails.
- Startup checks run in the background and sample up to 8 frames. If they fail, automation remains stopped; correct the reported issue and click Start again.
- Stop cancels the check; settings remain locked while checking. Results from a cancelled check cannot start a previous run.
- Character, minimap bounds and a unique player marker must pass on the same frame. Logs include template scores, thresholds and specific minimap or route errors.
- Imported route maps depend on the matching minimap layout. Select the correct route for the current map.
- Route files may use .json or -graph.json names; legacy built-in IDs and filenames remain compatible, including user-imported overrides.
- Built-in route names now identify Line 1 / Line 2 Area 1, Downstairs at the Forest, Monkey Forest 1, Ludibrium Free Market and Entrance of Golem's Temple.
- Server choices are Global Classic, China Classic, Taiwan Classic, Japan Classic, Korea Classic and Private Server.
- Taiwan, Japan, Korea and Private Server use generic recognition settings. Older Southeast Asia / Other settings migrate to Private Server.
- Verify that the chosen profile matches your game UI; these options do not add server-specific calibration.

7. Settings pages and recognition display
-----------------------------------------
- Tabs use one row: Basic, Combat, Assist, Lie Detector and Log.
- Assist combines Supply, Buffs and Item Pickup in three scrollable sections.
- Lie Detector contains the main alert switch, Test Sound and Remote Alerts.
- Below Window Source, Draw player, Draw monsters and Attack range are independent switches.
- Yellow player/red monster boxes show similarity scores; a cyan dashed range rectangle uses the same body-center anchor as combat.
- During combat the range shows the active run settings; while idle it uses saved settings. It can be enabled without player/monster boxes and hides if the current character detection is lost.
- The overlays are click-through and do not activate the app. The game still needs to remain in the foreground for keyboard input.
- While idle, selected monsters can be previewed. Drawing can be disabled without disabling recognition or minimap dots.
- Configure every key exactly as it is assigned in MapleStory.
- Enable only the HP, MP, buff, and item-pickup options you need.
- Confirm thresholds and intervals before starting combat.
- Use the log panel to verify detected targets, key actions, warnings, and startup checks.

8. Troubleshooting
------------------
- If the selected window is unavailable, restore the game, refresh the window picker and select its actual game window again.
- Check startup failure stages in the log: window source, permissions, frame size, character template, character recognition or minimap recognition.
- Failure messages use: "Startup check failed: <reason> (diagnostic code: <stage>)".
  - WINDOW_SOURCE / WINDOW_NOT_SELECTED: selected window, owning process, or unavailable window.
  - SCREEN_RECORDING_PERMISSION / KEYBOARD_PERMISSION: macOS recording or Accessibility permission.
  - CAPTURE / CAPTURE_BLACK / CAPTURE_RESOLUTION: capture failure, black frame, or a client area other than 1366 x 768.
  - CHARACTER_PROFILE / TEMPLATE_FILE_MISSING / CHARACTER_RECOGNITION: character selection, template files or matching failure.
    Character-template detail messages show the actual similarity scores and required thresholds.
  - MINIMAP_RECOGNITION: player-marker color, size, shape and surrounding minimap border.
    Player-marker detail messages distinguish a missing marker from multiple matching markers.
  - ROUTE_MINIMAP / ROUTE_MAP: a route that does not match the current minimap, or an unreadable route file.
- For frame-size errors, verify the game resolution and macOS display scaling; the recognition frame must be 1366 x 768 after Retina normalization.
- Mac capture transfers pixels through uncompressed TIFF in memory to avoid per-frame PNG compression. Resolution, colors and recognition thresholds are unchanged. Idle preview has a 120ms wait, so its displayed FPS is not the running recognition rate.
- If a character or monster is not detected, recapture a clean template without background or visual effects.
- If movement or attacks are incorrect, verify the selected mode, keys, attack ranges, minimap, and game resolution.
- Stop combat before changing maps, templates, key bindings, or major combat settings.
- After changing settings, stop the current run and press Start again to apply them.
- Logs retain the most recent 2000 lines. Foreground-loss messages are reported once per loss.
- Combat status counts monsters inside the configured horizontal and vertical attack ranges, with both limits shown.
- Runtime recognition continues during action waits. Observations older than 0.5 seconds are rejected; a last known player position has up to 1s grace. Stop releases held keys.
- A short-lived radar anchor is only for display; it does not create a successful character detection.

9. Remote alerts
----------------
- In Lie Detector > Remote alerts > Configure, enable Telegram, Slack and/or Discord and test each enabled destination.
- Discord and Slack: enter an official Incoming Webhook URL for the destination channel.
  Discord forum channels also need a numeric thread_id in the webhook URL.
- Telegram: create a bot with @BotFather, then enter its Bot Token and the destination Chat ID.
  For private chats, send /start to the bot first and use your numeric Chat ID, not a personal @username.
  Group Chat IDs are normally negative. Channel destinations may use @channel; the bot needs permission to post there.
- Valid alert changes save automatically for future alerts. Saving does not send a message.
- Only Send Test sends a real test message. Invalid drafts keep the last valid saved settings.
- Global Classic checks four entry prompts (figure tracking, Violetta, sound and text captcha) at up to 5Hz on the shared capture. A same-type native-scale match of at least 0.92 must persist for at least 0.5s (normally four samples across about 0.6s).
- Global entry templates target native 1366 x 768 prompts, not later minigame stages or scaled UI. Other server profiles keep the fixed-region gold-star detector, 0.88 threshold and 0.5s confirmation.
- Keep the main lie-detector alert enabled. A confirmed detection stops automation, plays the local sound,
  and sends one message to each enabled destination. Test Sound checks local audio only; it does not send remote alerts.
- Alerts go directly from this app to your configured platform, without the license server.
- A detection alert sends one plain-text line in the selected app language: "Checking for a lie detector."
  It contains no emoji, screenshots, character/server details, license keys or device IDs. Test messages are also single-line text.
- Sending runs in the background without automatic retries. Check the Runtime log for the result.
  If a request times out, check the destination before retrying to avoid duplicate messages.
- Settings use AES-GCM file encryption in ~/Library/Application Support/Okya/notifications.dat, with a private encryption.key in the same folder.
- On first upgrade only, legacy files without a local key trigger a read of the old Keychain key. The app validates the old ciphertext before saving the key locally; future launches use only that file. A system authorization prompt may appear during migration. Fresh installs do not access Keychain.
- Back up the key together with license.dat and notifications.dat. Failed or cancelled migration preserves old files and never resets the device ID.
- HTTPS uses the bundled CA certificates. Test delivery before relying on alerts.

Official website: https://maple.okya.app
