analytics.lic guide

What it does

analytics.lic runs alongside your hunting scripts and records, for every character you run it on:

Cycles: each stretch of hunting, resting, being dead or sitting idle, with why the hunt ended, and how long each step of a rest took (travel, looting, the bounty turn-in, healing...).
Kills by creature, with the silver on each corpse and the boxes found.
Silver: bank balances (the figure every "silver per hour" uses), plus box silver, vendor sales, bounty rewards, and what you spend at the locksmith, the locksmith pool and the priestess.
Bounties: every task the taskmaster offers, whether you keep it, remove it or used an expedite voucher; progress (7/11), time taken and the rewards.
Experience, fame, mind and encumbrance at the start and end of each cycle, and each login's totals.

Everything goes into one SQLite database on your computer, shared by all your characters and both games. You see it three ways: text reports in the game window, alerts and a daily digest in the game and on Discord, and the web dashboard, which reads your database in your browser. Nothing is uploaded anywhere.

Install

You need

Lich 5.23.0 or newer. The sequel and sqlite3 gems it needs ship with Lich.
bigshot for hunting, or your own script (see hunt_script in Settings). Rests are detected from bigshot's own status.
Optional: discordhook, for alerts on Discord.

Get the script

;repository download analytics.lic

or copy analytics.lic from elanthia-online/scripts into your Lich scripts folder.

Start it on every login

Run it on each character you want tracked. To have it start by itself:

;autostart add analytics

Add --dashboard on one character (;autostart add analytics --dashboard) if you want the dashboard to update live; one per computer is enough.

First run

Type ;analytics. It prints where the database is, which scripts it watches, and Ready.
A few seconds later it sends one quiet BANK ACCOUNT, so silver can be tracked from the start. That happens once per character, not every login.
It writes your settings file with every setting at its default. ;analytics help prints where it is. Change what you want, then restart the script (;kill analytics, then ;analytics).
Hunt as usual. Reports and the dashboard fill in as you go; the "typical" baselines need about five days of hunting.

Where things live: the database is analytics.db in Lich's data folder, shared by all characters. Each character's settings are in <Lich data>/<game>/<character>/analytics.yaml. ;analytics help shows both full paths for the character you are on.

Commands

Command	What it does
`;analytics`	Collect data for this character. Run it on each one.
`;analytics --dashboard[=PORT]`	Collect, and feed the web dashboard live (port 8080 unless you give one).
`;analytics serve [PORT]`	Feed the dashboard without collecting, or start feeding it inside a running collector.
`;analytics report <name> [range]`	A text report in the game window.
`;analytics status`	What the collector is doing: state, cycle, scripts watched, the dashboard link, the database.
`;analytics maintenance <task>`	`compact`, `vacuum`, `stats` or `backup`. See Maintenance.
`;analytics help`	The command list, and where this character's settings file and the database are.

While the collector runs, type the other commands as usual (;analytics report exp weekly). Lich won't start a second copy of a running script, so the collector catches them and runs them itself.

Text reports

;analytics report <name> [range]. Ranges are daily (the default), weekly, monthly, ytd and total.

Report	Shows
`character`	Every character side by side over today, the week, the month and the year: silver and exp per hour, bounties per hunting hour, kills, uptime, deaths, bank balances, idle time, encumbrance and item-limit rests.
`exp`	Experience and fame per character.
`bounty`	This character's bounties: completed, abandoned, success rate, average time and rewards; by type and creature; value per hour; and the task offers section: offered, removed, expedited, vouchers left, and what you removed.
`cycle`	Hunt, rest, dead and idle time: counts, averages, longest and shortest; exp and fame; encumbrance; rest reasons; deaths and the time between them.
`silver`	Where silver came from (corpses, boxes, sales, bounties) and went (locksmith, locksmith pool, priestess), the net, the bank change, and sales by vendor.
`kills`	Kills, boxes, box rate and silver per kill by creature.
`session`	This login next to today, the week, the month, the year and lifetime: silver, silver per hour and per hunting hour, exp and its rates, deaths, time logged in and hunting. A login lasts from when Lich connected to the game until you log out, even if that's days.

The dashboard

The dashboard is this website: analytics.elanthia.online. It runs in your browser and reads your own database; it never uploads it. It has an overview of every character (today's totals, each character's state and pace, the day's activity, alerts) and a page per character (performance and trends by day, week or month; rests; mind and load; hunting grounds; bounties and task offers).

Live from analytics.lic

Start the script with ;analytics --dashboard (or type ;analytics serve while it runs).
It prints a link like https://analytics.elanthia.online/?live=8080. Open it, or open the site and choose Connect.
Chrome and Edge ask once whether this site may access other apps and devices on your computer. Choose Allow: that is how the page reaches analytics.lic on 127.0.0.1. If you chose Block, change it under the site settings (the icon left of the address), Local network access.

The page then updates every five seconds. The script answers only this computer, and only this site (or pages served from your own computer) may read it.

Other ways to open your data

Database folder (Chrome and Edge): pick Lich's data folder, the one with analytics.db. It stays live with no server running.
A file (any browser): pick a copy or a backup of analytics.db. Shown as of when it was saved.

Other computers on your network

Older versions could open the dashboard to your whole network (lan). That is gone: the dashboard is now an https page, which browsers won't let talk to another computer over plain http, and serving the database to your network would hand all of it to anyone there. To view another computer's data, copy its analytics.db (or a backup) and open it as a file.

A fork, or your own copy of the site

Pages served from your own computer (http://localhost:...) can always connect. For a copy hosted somewhere else, add its origin to dashboard.allowed_origins and point dashboard.site_url at it (see Settings).

Settings

Each character has its own analytics.yaml, written with the defaults the first time the collector runs. Keep only the lines you change: anything left out uses the default. Restart the script after editing. Indent with spaces, never tabs; null (or an empty value) means off. A mistake in the file is reported once in the game window and the defaults are used instead.

The cycle: hunting, resting, dead

Setting	Default	Meaning
`hunt_script`	`bigshot`	The script whose running means "hunting". A list works too: `hunt_script: [bigshot, my_hunter]`.
`bigshot_status`	`true`	Read bigshot's own resting status, so its rests are detected without a `rest_script`. Only read while bigshot runs (it goes stale otherwise). Set `false` if you hunt with something else.
`rest_script`	none	Your own rest script (sell, loot, bank, return). While it runs, the cycle is a rest. Also what idle recovery starts.
`death_script`	none	Your death-recovery script; while it runs, the cycle is "dead". Death is also read from the game, so this can stay unset.
`rest_steps`	go2 travel, eloot eloot, ebounty bounty, eherbs healing, ewaggle spells	`script: label` pairs that time a rest: time goes to the first listed script that's running, and time with none running is "waiting". Add your own, e.g. `my_sell: selling`. These also mark a trip as a rest when another script stopped the hunt (ebounty turning in a bounty).

What is read from the game text

Setting	Default	Meaning
`parse_sales`	`true`	Record vendor sales (including promissory notes, gem pouches and containers) and spending at the locksmith, the locksmith pool and the priestess, so your selling scripts need no changes.
`parse_bank`	`true`	Record `BANK ACCOUNT` listings, and move the tracked total by every deposit, withdrawal and note. With no total yet, one `BANK ACCOUNT` is sent quietly a few seconds after starting.

Hunt limits and recovery (off unless set)

Setting	Default	Meaning
`max_hunt_minutes`	off	Ask bigshot to rest after one hunt has lasted this long.
`idle_warn_minutes`	`8`	Alert after this long with none of your scripts running.
`idle_recover_minutes`	off	After this long idle, walk to the room in `profile_room_map` and start `rest_script`. Needs a rest_script.
`profile_room_map`	empty	Where idle recovery walks to, by bigshot profile name (with or without the leading `<character>_`): `profile_room_map: { crags: 1234, torvek_cliffs: 5678 }`
`weapon_loadout`	off	A re-arm check while hunting. If your hands don't match, hunting pauses while it tries; after several failures you get an alert and a rest. `{ right: scepter, left: shield, gird: true, get_right: get my scepter, get_left: get my shield }`

Alerts, Discord and the dashboard

Setting	Default	Meaning
`alerts.no_kill_minutes`	`10`	Alert after hunting this long with no kills.
`alerts.silver_drop_pct`	`50`	Alert when today's silver per hunting hour is this many percent below the last seven days' average...
`alerts.silver_check_after_hours`	`2`	...once you've hunted this many hours today.
`alerts.daily_digest`	`true`	Send yesterday's summary once a day.
`alerts.death`	`true`	Alert when this character dies.
`discord`	`true`	Also send alerts through discordhook (see Alerts).
`dashboard.port`	`8080`	The port `--dashboard` and `serve` use. `;analytics --dashboard=9000` overrides it.
`dashboard.site_url`	`https://analytics.elanthia.online/`	The page the script's link opens. Change it only for a fork or your own copy of the site.
`dashboard.allowed_origins`	`[]`	Extra sites allowed to read the script, as exact origins such as `https://someone.github.io`. The project site and pages on your own computer are always allowed.
`verbose`	`false`	Extra log lines, for tracking down a problem.

dashboard.lan is no longer used; see why.

Example

hunt_script: [bigshot, my_hunter]
rest_steps:
  go2: travel
  my_sell: selling
  eloot: eloot
alerts:
  no_kill_minutes: 15
  daily_digest: false
dashboard:
  port: 9000

Alerts and Discord

Alerts show in the game window, and on Discord when discord is on and discordhook is running: start ;discordhook (with its webhook set up as that script describes) before ;analytics. With discordhook not running, alerts appear in the game only.

No kills for alerts.no_kill_minutes while hunting.
Silver drop: today's silver per hunting hour well below the last seven days' average.
Idle for idle_warn_minutes, and idle recovery starting a rest.
Death.
Missing armaments, when the weapon_loadout check couldn't re-arm.
Item limit: a rest because bigshot hit its item limit.
The daily digest: yesterday's hunting time and uptime, exp, kills, deaths, bounties and bank change.

What is recorded

One SQLite database, analytics.db in Lich's data folder. Every row carries its game and character, so the same name in GS4 and Shattered stays separate.

Table	Holds
`cycles`	Each hunt, rest, dead and idle stretch: start, end, reason, profile, exp, fame, mind and encumbrance at both ends.
`rest_steps`	Time per rest step.
`kill_stats`	Kills, corpse silver and boxes, per character, day, profile and creature.
`bounties`	Bounties you worked: type, target, area, count done of required, outcome, rewards.
`bounty_offers`	Every task offered, kept or not: what it was, how it ended, expedited or not.
`bank_snapshots`	Bank listings and teller moves, with the tracked total.
`silver_events`, `item_sales`	Box silver, sales, bounty silver and spending; each item sold.
`sessions`, `logins`	Each character's days, and each game login.
`vendor_visits`	Only filled by your own scripts through the hooks.

You can open it with any SQLite tool for your own queries. Several Lich sessions can write to it at once: a write that finds it busy waits and retries. On ;kill, whatever is still queued is written; if another session holds the database even then, the game window says how many writes were lost.

How the numbers work

Silver per hour comes from your bank balance, so it counts everything you deposit, whatever its source. Per hour means per hour logged in with the script running; per hunting hour divides by hunting time only.
Creature silver counts what a corpse had when you searched it. Coins picked up off the floor show up only in the bank balance.
Fame is only as fresh as the last EXPERIENCE output Lich saw. To see fame per hunt and rest, have your rest script run EXPERIENCE.
Bounties are stored once hunting starts on them; a task you remove at the taskmaster still shows in task offers. Progress follows the game's "N more" text.
Typical on the dashboard is the average of your own recent hours or days with real hunting (20 minutes in an hour, 2 hours in a day), so it needs about five of them before it means anything.
A login starts when Lich connected to the game. Restarting the script keeps the same login.

For script authors

Sales and bank balances are read from the game text, so selling and resting scripts need no changes. These hooks exist for anything the text doesn't cover. The module exists only once ;analytics has started in that Lich session, so guard the calls:

if defined?(GS4Analytics::SilverManager)
  GS4Analytics::SilverManager.take_snapshot          # a bank listing now
  GS4Analytics::SilverManager.record_vendor_silver(amount, vendor_type, vendor_name = nil)  # only with parse_sales: false
  GS4Analytics::SilverManager.record_vendor_visit(vendor, start_time, end_time, silver)
end

While parse_sales is on, record_vendor_silver is ignored so a sale isn't counted twice.

Maintenance and backups

Command	What it does
`;analytics maintenance stats`	Rows per table and the file size.
`;analytics maintenance backup`	A consistent copy in `analytics-backups/` next to the database, safe while other sessions write. The newest seven are kept.
`;analytics maintenance compact`	Removes bank rows that recorded no change.
`;analytics maintenance vacuum`	Rewrites the file to reclaim space.

Troubleshooting

The dashboard says it could not reach analytics.lic: Check the script is running with --dashboard (;analytics status shows the link), and that the port matches. In Chrome or Edge, check the site's Local network access permission is Allow (the icon left of the address).
"Port 8080 is already in use": Another program has it. Use another: ;analytics --dashboard=9000, or set dashboard.port.
Rests show as idle: If you don't hunt with bigshot, set rest_script to the script that rests, and add the scripts that run during a rest to rest_steps.
Silver per hour is zero or jumps: Silver is measured at the bank. Until the first BANK ACCOUNT listing there is nothing to measure from; after that, it moves when you deposit.
Fame never changes: Have your rest script run EXPERIENCE (see How the numbers work).
My settings change did nothing: Restart the script after editing. If the file has a mistake, the game window said so once, and the defaults are in use.

FAQ

Is my data sent anywhere?: No. The database stays on your computer. The dashboard page is downloaded from this site, but it reads your data inside your browser.
Can I run it on several characters at once?: Yes, one copy per Lich session, all sharing one database. Feed the dashboard from any one of them.
Does it work in Shattered?: Yes. Every row records its game, so GS4 and Shattered characters with the same name stay separate.
Where do I report a problem or suggest something?: Dashboard and ideas: elanthia-online/analytics. The script itself: elanthia-online/scripts. What's planned is in the roadmap.