black-sliver / poptracker

universal, scriptable randomizer tracking solution that is open source, runs everywhere and supports auto-tracking.

PopTracker

Powerful open progress tracker is a project to offer a universal, scriptable randomizer tracking solution that it is open source, runs everywhere and supports auto-tracking.

Getting started

This is work in progress. Some pre-existing packs work, some do not.

Download a binary release or build from source.

Drag & drop downloaded packs into the PopTracker window to install them without unpacking.
Alternatively copy or unpack tracker packs into one of the search paths EXEDIR/packs (not on macOS), HOME/PopTracker/packs, Documents/PopTracker/packs or CWD/packs.

Use the Load button in the top left corner to load a pack.

Do not load untrusted packs until some sort of fuzzing is done.

Binary release is Windows 64bit and macOS 64bit only at the moment (see Download prebuilt exe or app),
should compile on most unix-like OS (see Building from source).
WASM support still needs a lot of work.

Check BUILD.md, CONTRIBUTING.md, doc/OUTLINE.md and doc/TODO.md if you want to join in on the development journey.

Check doc/PACKS.md if you want to write a game pack for this tracker.

Upstream URL is https://github.com/black-sliver/PopTracker/

Screenshot

Download prebuilt exe or app

Head over to releases and unfold "Assets" of the latest release or pre-release to get a Windows exe or macOS app.

We have AppImage builds on the Community Discord for Linux. You still need to install which and a dialog provider (zenity, kdialog, matedialog, qarma or xdialog) to run them.

Building from source

See BUILD.md.

Supported/tested packs

• evermizer-tracker-package
• SoM-Open-Mode-Tracker
• iogr_emotracker_apokalysme v3.6
• Ender Lilies Tracker

more to be tested

Join the Community Discord to find pack repositories, follow updates and get support.

Location Color Key

Color	Meaning
Red	This check is not currently accessible.
Yellow	This check is not logically accessible, but the location can be reached through alternate methods (e.g. glitches, breaking key logic)
Orange	Some (but not all) checks at this location are accessible.
Green	All checks at this location are logically accessible.
Blue	The check at this location is visible, but you cannot currently access the check.
Other	Locations with mixed accessibility checks will have the corresponding colors mixed.

Colors can be customized by following instructions on the Color Picker page.

Press Ctrl+P to switch between "mixed" and "split" map location colors.

Auto-tracking

SNES Games

Requires SNI or QUsb2Snes (flash cart, emu, snes mini) or usb2snes (flash cart only). See their respective documentation.

PC Games

We do not allow direct access to process memory or sockets from Lua. Instead UAT can be used to receive "variables".

Archipelago Multiworld

Archipelago allows connecting to a Multiworld as a tracker. Click on the grey "AP" to connect to a server if the pack supports it. See doc/AUTOTRACKING.md for more details.

Bizhawk Connector

Preview, currently only when setting platform to "n64". See doc/AUTOTRACKING.md for details.

Other systems

No work has been done for other systems yet.

Version Numbering

• Major update (X.0.0) may break everything
• Minor update (0.X.0) may change render output (i.e. window captures break)
• Revisions (0.0.X) should only fix bugs and add non-breaking features

Plug-Ins

Currently there is no plug-in interface.

If you want to work towards implementing such a system, please check PLUGIN LICENSE ADDENDUM.md for licensing considerations.

User Overrides

Users can override files from packs by creating a folder with the same file structure as in the pack, named .../user-override/<pack_uid> where ... is any one of Documents/PopTracker, %home%/PopTracker or AppPath.

Portable Mode

When creating a file called portable.txt next to the program (not macos) or next to poptracker inside the AppBundle (macos-only), the app runs in portable mode, which changes the default pack folder to be next to the program (not in home folder) and disables asset and pack overrides from home folder (only allows overrides from program folder).

poptracker's Issues

ZIP support

Is there interest in Lua autotracker support?

Hi, I'm interested in expanding support in Poptracker for Hamsda's OOT pack and my autotracking fork. Emotracker has deprecated their Lua support, and I'm concerned they will remove this (perfectly functional) option leaving N64 packs with no way to run autotracking.

So I want to ask before I get started - is there any interest in this project for supporting autotracking via Lua sockets? This would allow autotracking for N64 packs. It looks like only SNI and Archipelago are currently supported (not sure what UAT is.)

I plan to add support for my fork of the ConnectorLib lua that was written by WarpWorld for their crowd control software. It's the same script that Emotracker uses for the Lua autotracking option.

Thanks👋

PopTracker.json - "null" vs "false"

If you change hide_cleared_locations, hide_unreachable_locations or log to 'true', when you return to the file, you might try changing them to 'false' to turn them off. Confusingly, this leaves these switches enabled, and they actually have to be set to 'null' to be turned back off. Better handling of this issue might reduce confusion and support inquiries.

Custom colors not applying to hover tooltips

When you use custom colors through a colors.json file, it does successfully apply these colors to icons on the map, but not to text in the hover tooltips. See this image for an example:

I have made glitch locations blue as a custom color, which does show in the map icon, but not when I hover over to see the actual locations

Add protocol to communicate between pack and 3rd party app

Propose and implement a simple, websocket-based protocol that allows packs' Lua to get values from 3rd party applications (bridge application or in-game mods).

• We don't want raw sockets, raw memory access or DLL loading in Lua for security reasons
• If the protocol is simple enough to use and implement, there is little reason to prefer other options
• Websockets are the only option when run inside a web browser (which is not working yet)

[SNES Autotracking] delete may wait for socket timeout

run destructor in its own thread (if compile time option says we should)

Readme links don't resolve correctly when opened via Notepad++

When double-clicking links from the README.md file in Notepad++, the ) from the end of the hyperlink tag gets included as part of the link, so
https://github.com/black-sliver/PopTracker/releases
resolves as
https://github.com/black-sliver/PopTracker/releases)

This should be resolvable by adding a space between the actual link and the ).

Location names containing `:` cannot be referenced in access rules

I tried to add access rules to a location using the result of another location "@ASLBBoss/Goal: Asylum Brain Tank".

Doing so prints the below error to standard output:
Could not find location @ASLBBoss/Goal for access rule!

Notably, the location appears to have been cut off at the :. I'm guessing this is because : is usually used to refer to a count of a consumable item:

PopTracker/src/core/tracker.cpp

Line 735 in f032142

auto p = s.find(':');

[Feature] NDI Support for broadcast view

A NDI support for the broadcast view could allow easier multi-pc setups for streaming.

Wiki page about NDI : https://en.wikipedia.org/wiki/Network_Device_Interface

It is actually added to emotracker's broadcast allowing :

• Streaming PC to receive the content of the broadcast view without the need of a screen/window capture of the PC with the tracker (so the tracker can be set up on the gaming PC)
• Use of NDI source with transparency capacities instead of "capture window" which would force the use of a chroma key to have a transparency

If NDI is not a target choice, maybe a web socket could allow an equivalent result.

Poptracker doesn't open

Hello,
This is an issue I've had for a while, but I am only just now posting an Issue about it because I downloaded the latest version at it is still occurring. Whenever I open Poptracker, the program opens into my taskbar but does not open on any of my screens and displays a white box as the preview.
Demonstration: https://youtu.be/s96RYjlA6Dg
If there is any way for me to provide better information, like a log file, I would gladly do that if pointed to where that info can be found.
Thanks, MrPokemon11

Missing dependency on Linux

Please add the package 'lua' to the listed dependencies in BUILD.md

macOS packs location inside APPBUNDLE

For macOS, packs need to be installed inside the app bundle. This is mentioned in the README.md, but vaguely worded.

1. From Finder, alt-click poptracker.app, and select Show Package Contents.
2. Navigate to Contents/MacOS. Full path should read poptracker.app/Contents/MacOS
3. Create a folder named packs, and drop content into that folder.

I've attached a photo of a Terminal highlighting this structure. Hope that helps to clarify some of that!

Implement auto-loading json from pack's root directory

• as used in Old Super Metroid and ALTTP Rando: https://github.com/Gilgatex/alttpsmemotracker

Implement argument to lua access rule

• as used in Hamsda/OoTR

    "access_rules": [
      "deku_reg,$has_age|child,setting_forest_open",

Add SA-1 rom mapping for SNES

Might get around to this later myself, but figured opening an issue first would be best.

SA-1 uses an different mapping than the four mappings supported currently (most notably, BWRAM at banks 0x40-0x43), and any pack for an SA-1 game will need access to at least BWRAM (access to WRAM is fishy) for auto-tracking.

Assets loading from config directory

Hello there!
First of all, I want to mention that I use GNU/Linux and while theoretically it applies to all versions, I believe it's practically only this since MacOS and Windows have compiled releases.
Yesterday, I wanted to play a multiworld with some people over Discord and I was suggested using this.
Thing is, when I launched it, the UI buttons didn't load.

Having the assets in the same directory as the binary fixes it.
Now, later I found out (or rather was told) that this is mentioned in the BUILD.md and I must have skimmed over it.
But since it creates a ~/.config/PopTracker (and I assume a folder inside %APPDATA% as well), why not load the assets from there so it doesn't matter what folder one is in?
I have a specific way of organising my files and folders and this one doesn't really fit without always being in a specific directory.
For example, I like to have all my software I compiled myself in ~/bin (part of $PATH) so that I can just call it from anywhere which just isn't feasible as of right now because it doesn't load any assets and can't even connect it to AP if it hasn't loaded the specific file.

EDIT: Reason why I'm in the build directory in the screenshot is simple. It's a habit of mine to go inside the build folder and run it from there for the first time before I actually include it into my system.

Pack override support

"toggle_badged" item type not implemented

this shows up in several minish cap tracker packs

Implement JsonItem::MaxCount

• as used in Hamsda/OoTR
  Error running "scripts/init.lua": [string "scripts/update_shared.lua"]:38: Unknown property "MaxCount" for "JsonItem"!

• allow reading

• allow writing

• save

Use std::filesystem to fully support windows unicode filenames

current state of things:

• on non-windows, we expect everything to use UTF-8, having it just work
• we use the "ANSI" version (and fopen()) for most path-related things on Windows
• we have to convert paths from "ANSI" to UTF-8 when saving to JSON (WIP)
• we have to convert back to "ANSI" when loading JSON containing paths (WIP)
• the user can not save/load from paths that can't be represented by their locale

goal:

• use std::filesystem::path to abstract the underlying path encoding
• end up using the "Wide" version for Windows API things
• allows save/load from paths with any symbols in it

problems:

• we still target macos 10.12, which does not have std::filesystem support, so we need to add "emulation" for systems that don't have std::filesystem
• we use FILE* instead of streams in a lot of places. there was a good reason to try and avoid streams, but it's not worth the hassle with std::filesystem

Segfault on Fedora Linux with provided AppImage

I get a segfault running the latest prerelease AppImage:

> ./PopTracker-0.25.8-x86_64.AppImage
PopTracker 0.25.8
Checking for update...
HTTP: connecting via https to api.github.com  for /repos/black-sliver/PopTracker/releases?per_page=8
Ui: Init SDL 2.0.20...
[1]    4585 segmentation fault (core dumped)  ./PopTracker-0.25.8-x86_64.AppImage

I'm running Fedora 38 on PopTracker 0.25.8.
I get no segfault building this from source with g++ 13.2.1.

Scoutable and glitched reachable act as unreachable when both true

Referring to this line:

PopTracker/src/core/tracker.cpp

Line 857 in 445db8a

return (glitchedReachable && !inspectOnlyReachable) ? AccessibilityLevel::SEQUENCE_BREAK :

And this conversation in the Discord:

• Initial explanation
• Further exploring
• Found the code responsible

It's my understanding that currently scoutable and glitched reachable are mutually exclusive - when both are true, PopTracker treats a location as unreachable. I believe it should act as glitched reachable (yellow), since a location being scoutable is good, but if you can obtain it out of logic, that's more useful to a player.

Implement "Level" result for LUA access rules

• LUA access rules ($function) should be able to return the level of accessibility as second result.
• Define constants in LUA global AccessibilityLevel, as used here

Implement Composite Items

• as used for Boomerang and Bow from LTTPR
• (New) Super Metroid + LTTP Rando (v3.5.0)

see end of Item Section in PACKS.md

see https://github.com/emosaru/alttpr_emotracker_emosaru/blob/master/items/common.json#L80

[SNES Autotracking] fix locking mess

use client.set_timer() instead of std::this_thread::sleep_for()

Items with pink background should be transparent

as seen in ALTTPR pack

Proposed solution: if image has no alpha channel and no transparent slot in the palette (indexed), make top-left or bottom-right color transparent (not sure yet)

Implement "Captured Item"

• Manually assign items to locations/sections when receiving hints
• Lua Interface: LocationSection::CapturedItem assigns 1 item to a section
• Automatically unlock items that are assigned to sections when looting