Merge branch 'master' into speedup-rules

CREDITS.md

@@ -4,6 +4,7 @@
 
 * [black-sliver](https://github.com/black-sliver)
 * [sbzappa](https://github.com/sbzappa)
+* [coavins](https://github.com/coavins/)
 
 ## Other Contributors
 

README.md

@@ -8,9 +8,10 @@ This is work in progress. Some pre-existing packs work, some do not.
 
 Download a binary release or build from source.
 
-Copy or unpack tracker packs to `EXEDIR/packs`, `HOME/PopTracker/packs`, `Documents/PopTracker/packs` or `CWD/packs`.\
-On Windows, it will also find packs installed in EmoTracker.\
-On macOS, EXEDIR is *inside* the app bundle, meaning `HOME/PopTracker/packs` is preferred.
+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.
 
@@ -88,6 +89,10 @@ We do not allow direct access to process memory or sockets from Lua. Instead
 tracker. Click on the grey "AP" to connect to a server if the pack supports it.
 See [doc/AUTOTRACKING.md](./doc/AUTOTRACKING.md) for more details.
 
+### Bizhawk Connector
+Preview, currently only when setting platform to "n64". See
+[doc/AUTOTRACKING.md](./doc/AUTOTRACKING.md#supported-interfaces) for details.
+
 ### Other systems
 No work has been done for other systems yet.
 
@@ -103,3 +108,15 @@ Currently there is no plug-in interface.
 If you want to work towards implementing such a system, please check
 [PLUGIN LICENSE ADDENDUM.md](PLUGIN%20LICENSE%20ADDENDUM.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).

doc/OUTLINE.md

@@ -1,95 +1,50 @@
 # PopTracker Overview
 
-This is a rough overview of internals and what we (have to) provide and what dependencies we have.
+This is a rough overview of internals and what we want to provide.
 
 Check linked docs for specifics.
 
 ## Goal
 - scriptable tracker and map tracker, similar to existing solutions
 - open source, platform independent 
 - runs in browser and on desktop
-  - have a Makefile that builds WASM blob, Linux binaries, Windows exe
-  - OSX support?
+  - have a Makefile that builds WASM blob, Linux binaries, Windows exe and macOS app bundle
 - auto-tracking support
-  - usb2snes interface
+  - see [AUTOTRACKING.md] for currently implemented things
   - more TBD
 - provide an interface that is compatible to existing packs
+- maybe add nicer interfaces on top or in parallel
 
 See [TODO.md](TODO.md) for current state of things.
 
 ## WASM work-arounds
-- `while(true)` does not work in WASM, so we define an interface `App` that
-  - implements a mainloop on desktop
-  - hooks into AnimationFrame via `emscripten_set_main_loop` in WASM
 
 ## UI requirements
-- item/status "icons" inside hbox/vbox/grid
-- map display: custom widget
-- map "icons" drawn in mapwidget's render()
-- hover -> tooltips -> floating regular widgets/containers
-- have "icons" be just widgets, state/image updated from back-end events/signals
-- use one TrackerView(Tracker*) widget to link up state with ui
-- we may require a "texture store" to support WebGL on mobile
-- layout.json => LayoutNodes => Widgets
-
-see [UILIB.md](UILIB.md) (outdated)
-
-NOTE: UI needs a lot of rework.
-
+see [UILIB.md](UILIB.md)
 
 ## Interface ideas
-### Packs
-```
-class Pack abstracts away Filesystem
-    ::Pack("path") loads a pack, where path can be a directory or .zip file containing a manifest.json
-    ::ReadFile(std::string fn,std::string& buf) will read file `fn` of the package into buffer `buf` and return a result code (no exceptions)
-    static ::ListPacks() returns a list of packs
-    ::ListVariants() returns a list of available variants for the pack
-    ::getVariant() returns currently active variant (or "" if none is active)
-    ::setVariant("variant") sets the active variant, used when resolving paths
-```
-
-Note that std::string allows easier integration with C code than a std::stream.
+std::string allows easier integration with C code than a std::stream.
 
 We may want to use mmap or raw pointer in the future, see [Ideal ZIP](#ideal-zip).
 
 ### Lua Glue
-since packs use lua to do actual stuff, we map c++ classes into lua.
-See [LUAGLUE.md](LUAGLUE.md) for the lua interface code.
+Since packs use Lua to do actual stuff, we map C++ classes into Lua.
+See [luaglue/README.md](https://github.com/black-sliver/luaglue/blob/main/README.md) for the lua interface code.
 
 ### Game pack interface
 see [PACKS.md](PACKS.md)
 
 We do not use the data directly, but instead load it into objects via
 Class::FromJSON, which are then used for to the actual (UI) implementation.
 
+## WASM support
+At some point PopTracker should be able to run inside a webbrowser using
+[WASM](https://en.wikipedia.org/wiki/WebAssembly).
+Most or all dependencies should work with emcc, but UI/window handling is not done yet nor is a virtual file system.
 
-## Back-end requirements
-- Lua VM
-- JSON parser
-- UI/Layout abstraction (JSON -> Widgets -> Pixels)
-
-## Base System / Dependencies
-- libsdl
-- libsdl_ttf
-- libfreetype as dependency of sdl_ttf
-- libsdl_image
-- libpng as dependency of sdl_image
-- zlib
-- liblua
-- json.hpp - https://github.com/nlohmann/json + patch to allow trailing commas
-
-## Linking
-emcc for web/wasm deployment provides some (specialized) versions of some libs:
-- SDL2
-- SDL2_image
-- SDL2_ttf
-- libpng
-- zlib
-- and their dependencies
-
-for now we link the libraries dynamically on Linux and use prebuilt SDL-devel (mingw) libs on Windows,
-but a more comlpex source tree + Makefile could integrate them as well
+- `while(true)` does not work in WASM, so we define an interface `App` that
+  - implements a mainloop on desktop
+  - hooks into AnimationFrame via `emscripten_set_main_loop` in WASM
 
 ## UI-Data-Bindings
 - signal Tracker::onLayoutChanged -> Ui::TrackerView::relayout

doc/PACKS.md

@@ -72,9 +72,10 @@ Configures behavior of the pack.
 
     {
         "smooth_scaling": true|false|null, // configure the image scaling method. null = default = currently crisp
+        "smooth_map_scaling": true|false|null, // configure the image scaling method for maps. null = default = smooth
     }
 
-Currently **not** user overridable.
+NOTE: User overrides for settings are merged with the pack, replacing individual keys, not the whole file.
 
 
 ## Lua Interface
@@ -102,8 +103,11 @@ The following interfaces are provided:
 
 ### global ScriptHost
 
-* `bool :LoadScript(luafilename)`: load and execute a lua script
+* `bool :LoadScript(luafilename)`: load and execute a lua script from absolute filename inside pack
   * `require` can be used instead (since PopTracker 0.21.0)
+  * `require` behaves mostly like Lua require since 0.25.6
+    * `"foo.baz"` will try `/scripts/foo/baz.lua`, `/scripts/foo/baz/init.lua`, `/foo/baz.lua` and `/foo/baz/init.lua`
+  * `...` contains mod name for relative require since 0.25.6
 * `bool :AddMemoryWatch(name,addr,len,callback,interal)`: add a memory watch for auto-tracking, see [AUTOTRACKING.md](AUTOTRACKING.md)
 * `bool :RemoveMemoryWatch(name)`: remove memory watch by name, available since 0.11.0
 * `bool :AddWatchForCode(name,code,callback)`: callback(code) will be called whenever an item changed state that canProvide(code). Only available in PopTracker, since 0.11.0, will return a reference (name) to the watch since 0.18.2. Use "*" to trigger for all codes since 0.25.5.
@@ -130,12 +134,13 @@ a string in the form of `"1.0.0"` -- **TODO**: move to Tracker.PopVersion ?
 ### global AccessibilityLevel (enum)
 
 a table representing an enum with the following constants: \
-`None`, `Partial`, `Inspeect`, `SequenceBreak`, `Normal`, `Cleared`
+`None`, `Partial`, `Inspect`, `SequenceBreak`, `Normal`, `Cleared`
 
 
 ### other globals
 
 * `DEBUG` set to true to get more error or debug output
+* `require` function, see [ScriptHost:LoadScript](#global-scripthost)
 
 
 ### type LuaItem
@@ -232,7 +237,8 @@ a table representing an enum with the following constants: \
 
   + img_mods filter to be applied on the img
     - `@disabled`: grey-scale
-    - `overlay|path/to/img.png`: draw a second image over it
+    - `overlay|path/to/img.png|overlay_filters...`: draw a second image over it; overlay_filters are applied to overlay (since 0.25.6)
+    - NOTE: order matters, applied left to right
   + inherit_codes: true will make stage3 provide codes for item, stage1, 2 and 3 (default true)
 
 * `"toggle"`:
@@ -400,7 +406,9 @@ Locations define drops on maps, rules to have them accessible as well as the loo
 Each `map_location` is a square on the map and shows a popup with individual chests.
 
 **Rules:**
-Rules starting with `$` will call the lua function with that name, `@<location>/<section>` will use the result of a different access rule, other rules will just look at items' `code` (runs ProviderCountForCode(rule)).
+Rules starting with `$` will call the Lua function with that name, `@<location>/<section>` will use the result of a different access rule, other rules will just look at items' `code` (runs ProviderCountForCode(rule)).
+
+Rules starting with `^` interpret the value as AccessibilityLevel instead of count. That is `^$func` can directly set the AccessibilityLevel, sometimes removing the need for `[]` and `{}` (see below). Only available in PopTracker, since 0.25.6.
 
 For `$` rules, arguments can be supplied with `|`. `$test|a|b` will call `test("a","b")`.
 The return value has to be a number (count) or boolean (since v0.20.4).
@@ -413,7 +421,9 @@ Rule-goups inside `{` `}` are a different set of rules to mark the section as "c
 
 `{<checkrule1>, <checkrule2>}` in example above are combined as: `(<checkrule1> AND <checkrule2>)` have to be met to check.
 
-In PopTracker (since 0.19.1) rules can be specified as json array instead of string, which allows to use `,` inside names or arguments
+Individual rules can be specified as json array instead of string, which allows to use `,` inside names or arguments. Only available in PopTracker, since 0.19.1.
+
+Rules can be specified as a single string, which is equivalent to `[[string]]`. Only available in PopTracker, since 0.25.6.
 
 **Parent:**
 With `"parent"`, the location's parent can be overwritten. Since PopTracker v0.19.2.

doc/README.md

@@ -8,11 +8,11 @@
 
 ## Internal API
 
-* [Lua Glue](LUAGLUE.md)
+* [Lua Glue](https://github.com/black-sliver/luaglue/blob/main/README.md)
 * [UI Lib](UILIB.md)
 
 
 ## Misc
 
-* [Project Overview](OUTLINE.md) (outdated)
-* [TODO](TODO.md) (outdated)
+* [Project Overview](OUTLINE.md)
+* [TODO](TODO.md)

doc/TODO.md

@@ -2,36 +2,26 @@
 
 Check [OUTLINE.md](OUTLINE.md) to get an overview of everything.
 
-## Current Plans
-see [github projects](https://github.com/black-sliver/PopTracker/projects) (outdated)
-
 ## Help wanted
 - OSX .dmg
-- Custom application icon
 - Fancier GUI
   - Better widgets ("real" buttons)
   - Nicer icons (I'm not an artist)
 
 ## General Stuff
 - isReachable optimizations:
-    - do not call into Lua from updateLocationState(): prebuild cache
     - invalidate only parts of _reachableCache when toggling items?
     - update location state on next frame instead of immediately (start of auto-tracking)
     - try to determine if location state needs update?
 - show version somewhere in the app
 - MemoryWatch: only run callback if all bytes of a watch have been read to avoid potential races (this has to add race-free bool to SNES::readBlock)
-- auto-tracking for N64?
 - pins
 - notes
-- background color of groups/titles
 - alignment of widgets inside widgets
-- Makefile: 32bit exe (static linking is currently somewhat broken)
 - Show error (+reason) when loading a pack fails
-- Log/console/error window as part of the UI
+- Log/console/error window as part of the UI (currently --console and stdout in shell/prompt exists)
 - Remove toolbar and put everything inside a context menu on desktop?
-- Update websocketpp, update asio (or use a different websocket implementation)
-  - included websocketpp is patched to allow std::thread on mingw
-  - included asio is the latest one that works with websocketpp 0.8.1
+- Update websocketpp, update asio
 - Item: `swap_actions: <bool>` (swaps left and right mouse button, alttpr)
 - Map/Locations:
   - number overlay on map (X unreachable red, Y reachable white)
@@ -41,6 +31,9 @@ see [github projects](https://github.com/black-sliver/PopTracker/projects) (outd
 - build with `-D_FORTIFY_SOURCE=2`, `-pie`, ASLR, RELRO ?
 - fuzz lua and json interfaces
 
+## Docs
+- compile README to HTML and open local copy with F1
+
 ## WASM
 - custom html, to only have canvas. Use js console for stdout and stderr
 - sync sdl window with html canvas (size)
@@ -75,17 +68,15 @@ see [github projects](https://github.com/black-sliver/PopTracker/projects) (outd
   - a uniform logic for relayout has to be found
   - a lot of hacks to make the current model somewhat work (see `// FIXME:`s and `// TODO:`s in source)
 - Responsive UI
-  - Toolbar hover/pressed
   - Pack-loading button-widget
 
 ## Random Notes
 ### Data additions
 - Item::ID in json? Auto-generated at the moment
 - Location::ID in json? Concat of names at the moment
 - Unique ID for actual drops (locations' sections' checks) so we can have the same drop on two maps (detailed and overview)
-- Location/section help/info (requirements to reach it)
+- Location/section help/info/hover text (requirements to reach it)
 ### Other stuff
-- enum class Ui::MouseButton in Mouse Events (instead of int and C-style enum)
 - enum flags Ui::Map::LocationState with operator|
 - (Evermizer: `settings_popup`) Layout: `header_background`
 - (Evermizer) Layout: header_content: adds a button to the header