Note: Please do let me know of any misbehaviours or desired improvements not already on the list.
The information below is copied from the master README; it may go out of date, so it's better to check the latest version from Github if the below doesn't seem to match. And please, raise an issue or ask a question if you notice the documentation isn't helping enough!
How does it work?
Once the mod is installed, using it is relatively simple:
- Use the shortcut button "Resource monitor marker" to drag-select at least one ore entity in a patch (like using a blueprint).
- Can't find the shortcut button? You may need to add it to the shortcut bar.
- If everything went well, you should now see a blue overlay showing up on top of the ore(s) you clicked, and growing as YARM finds their neighbours, and their neighbours, etc., until the entire ore patch has been scanned.
- After the scan, you have 2 seconds to select another ore of the same kind, which will be added to the same site.
- If you tap the ground instead, you will cancel the site creation.
- If you tap a different kind of ore instead, you will instantly create the site and start a new one on the other ore.
- Upon the expiry of those 2 seconds, the site will be created and a message will be shown informing you of its name and the amount of ore found in it.
- Sites can be renamed at any time! The default name is just a suggestion.
By default, YARM shows only sites that are about to expire (i.e., less than 10% of their initial amount remaining). There are buttons available to change the filter to either "no sites" (which never shows any sites at all!) or "all sites" (which never hides them).
Each site has some buttons associated with it:
- The 'ab|' button allows you to rename the site. This can be useful to prevent auto-naming from overwriting one of your sites with another.
- Note: Names may not be longer than 50 characters!
- The 'eye' button opens the map to the center of the ore site.
- The 'X' button allows you to delete the site. When first clicked, it turns red; click it again within 2 seconds to confirm deletion, or leave it alone to cancel it.
- The '+' button allows you to expand an existing site. Click the '+' for the site you want to expand, then use the marker tool to select the new ore site you want to add to the existing monitor. Sites are not renamed by this process.
- NB: For ease of use, the '+' button also activates the resource monitoring marker shortcut.
- Pressing the '+' while it's red (which indicates addition in progress) will finish the adding process (and update the site, if it's changed).
- While expanding a site, a blue overlay (identical to the one used when creating the site in the first place) will highlight the ores that comprise the site currently. For performance reasons, the overlay appears gradually rather than all at once.
Sites are bound to forces (i.e., teams), so any sites you add will be visible to your teammates.
Endless resources (by default, oil, but mods exist for others) are supported; the percentage full is calculated similarly to how the base game does, but independently recalculated (
percent = entity.amount * 100 / entity.prototype.normal_resource_amount). However, please note the estimated time to depletion is likely miscalculated -- it's expressing the time to a nominal 0%, which is not possible with Factorio endless resources (they stop at 20%).
YARM's remote interface is grown as needed; there are only a few functions currently:
remote.call("YARM", "reset_player", player_name_or_index): sets the target player's character to be whatever the player has selected (if it's of a compatible type, of course) and clears out internal data relative to the player.
- Note: this is considered deprecated, as the player character is no longer (since v0.8) being changed to allow remote viewing.
remote.call("YARM", "reset_ui", player_name_or_index): destroys the target player's YARM UI, forcing it to be recreated (hopefully correctly) at the next UI update cycle (about every 5 seconds).
remote.call("YARM", "set_filter", player_name_or_index, new_filter): provides programmatic hooks to change the active filter. The filter value may be 'none', 'warnings', or 'all' -- other values are unsupported. The previously active filter is returned.
remote.call("YARM", "get_on_site_updated_event_id"): returns the identifier for the
on_site_updatedevent, detailed below. You should probably call this every time mods are initialized, as it is set in the main
Additionally, there is one event:
on_site_updatedis periodically raised whenever a site's ore count and stats are brought up to date. The event contains:
force_name, the name of the force owning this site
site_name, the name of the site that just finished updating; site names are unique within a force
ore_type, the entity.name of the resource entities tracked in this site (e.g.,
amount, the number of ore units remaining in the site
ore_per_minute, the number of ore units mined in a minute on this site, based on the number mined since the last update
remaining_permille, the ratio of ore remaining versus the initial amount from when the site was created
- NB: permille is analogous to percent, but multiplied by 1000 instead of 100; its symbol is ‰
Visit the Github releases page for manual downloads, if you prefer them. I also would greatly appreciate that bug reports be filed as a new issue for greater visibility (promise you'll get quicker response, too)..