Help & user manual

Start here

This is a chest counter for Total Battle clans. You record the chests your members open, it does the scoring, ranking and reporting for you — so clan rewards go to the people who actually earned them.

Getting a clan running takes about fifteen minutes:

1. Add your members exactly as their names appear in Total Battle — step 1.
2. Match the chest types to what your game shows, and give each one a point value — step 2.
3. Log chests daily with the quick log on the dashboard — step 3.
4. Agree a weekly routine so the numbers keep coming in — step 4.
5. Read the leaderboard on reports day and hand out rewards — step 6.

Create a free clan account

How it connects to Total Battle

Read this first. Total Battle has no public API, data export or add-on system, and this is an independent tool — it is not affiliated with, endorsed by or sponsored by the makers of the game. Nothing here reads your account, and you should never give your game login to any third-party site, including this one.

So the connection is a reporting workflow, not a technical one: what your clan can see in the game gets recorded here in seconds, and the counter turns it into history, scores and rankings that the game does not keep for you.

Where the numbers come from

What to record

One entry is: who got the chests, which chest type, how many, when, and optionally where from (the source) plus a note. That is all the counter needs. Whether your clan counts every chest opened, only clan and event chests, or only chests from a specific tournament is your decision — just make it the same rule for everyone, and write it in the note field when an entry is unusual.

1. Build your roster

Open Members and add one row per person in your clan.

• Name in game — type it exactly as Total Battle shows it, including capitals and spaces. Matching names is what makes the leaderboard believable, and the CSV import relies on it.
• Game ID — optional, but useful when two people pick similar names, or when someone renames.
• Note — anything you want to remember: “joined 12 May”, “alt of Aragorn”, “on holiday”.
• Active member — untick when someone leaves. Their history stays and still counts in past reports, but they drop out of the quick log and the “needs a nudge” list.

A member here is just a name you track. It does not give anyone a login — that is Team access. Someone who renames in game should be renamed here too: edit the row rather than adding a second one, so their history stays in one place.

Deleting a member also deletes every chest entry recorded for them. To take someone off the list without losing history, untick Active member instead.

2. Set up chest types and points

Every clan starts with a default list (Bronze, Silver, Gold, Platinum, Clan, Event, Dungeon, Boss). These are a starting point, not gospel — rename them to match what you actually see in your game client on the Chest types page. Names differ between events, seasons and translations, so use whatever your clan says out loud.

Points are the whole trick

A member's score is quantity × points, added up over the period. Points let a rare chest outweigh a pile of common ones, so nobody can farm the leaderboard with the cheapest chest available. A reasonable starting scale:

Rarity only sets the colour used in tables and charts. Points do the scoring. Change points whenever your clan agrees a new balance — past entries keep the quantity you recorded, and their score is recalculated with the new value, so the whole leaderboard stays consistent.

Untick Show when logging chests to retire a chest type after an event without deleting anything. Deleting a chest type removes every entry that used it.

3. Log chests every day

Quick log — the fast way

The dashboard has a quick log: pick the member, pick the date, then type quantities into the boxes for each chest type and press Save chests. One member with five chest types is one save, not five.

1. Choose the member.
2. Set the date — leave it on today, or back-date an entry you forgot yesterday.
3. Pick a source (clan, event, dungeon, battle, quest, shop, VIP, gift, other).
4. Type quantities. Leave a box empty or at 0 for chest types that do not apply.
5. Save. Every box with a number becomes its own entry, so you can correct one later without touching the rest.

Single entry — when detail matters

The Log chests page records one line with a note attached — handy for “tournament reward”, “compensation from support” or anything you will want to explain in three weeks.

Fixing mistakes

The Chest log lists everything with filters for period, member, chest type and source. Officers can edit or delete any entry; members can only change the ones they logged themselves. Every entry shows who logged it, which settles most arguments before they start.

Habit that saves you: log on the day. Chest counts are almost impossible to reconstruct a week later, because the game does not keep a history you can go back to.

4. A weekly clan routine

Clans that get value out of this settle on a rhythm. One that works:

Announce the rule up front — “chests are counted Monday to Sunday, rewards go to the top three by score” — and pin it in your clan chat. The counter only measures; your clan decides what the measurement is worth.

Automatic counting

Typing chests works, but it does not scale past a handful of members. Three automatic routes do the counting for you, and all three end in the same place: a review queue, where you confirm what was read before it touches the leaderboard. Nothing is ever scored on a guess.

1. Read a screenshot

1. Take a screenshot of a rewards, clan or event screen in Total Battle.
2. Upload it on Auto capture, pick the date and source.
3. The server reads the text, matches names against your roster and chests against your chest types, and shows every line with a confidence score.
4. Fix anything marked check, untick what you do not want, then apply.

Accuracy depends on the screenshot. Crop to the list, keep the game at a readable size, and avoid heavy background art. Clean captures usually come through at 100%; stylised fonts and small phone screenshots need more correcting. If the server has no OCR engine installed, the upload box says so and the other two routes still work.

2. Paste a chest list

Paste from clan chat, Discord, a phone OCR app or a spreadsheet. The parser reads the shapes people actually write, and understands short forms without any setup:

Aragorn: 3 gold, 5 silver     → 3 Gold Chest + 5 Silver Chest for Aragorn
Boromir - Boss Chest x1       → 1 Boss Chest for Boromir
Legolas: gc 2                 → 2 Gold Chest for Legolas   (initials work)
• 2 Dungeon Chest             → 2 Dungeon Chest (member taken from the form)

Names it cannot place are shown as “unknown name” with a button to add them to the roster. Wording it cannot place — an event chest, a translation, your clan’s slang — can be taught with Teach the parser, and it is remembered for every future capture.

3. Let a bot post for you

Automation & API issues tokens for outside scripts: a Discord bot reading !chest messages, a phone shortcut, a Google Sheets script, anything that can make an HTTPS request. They post chest text or structured lines, and it lands in the same queue.

curl -X POST "<your site>/index.php?r=api.chests" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Aragorn: 3 gold, 5 silver", "source": "clan"}'

Give each bot its own token so you can revoke one without breaking the rest. A token marked trusted applies confident lines immediately; anything the parser is unsure about still waits for a human, in either mode. Limit: 30 requests per minute per token. There is also a leaderboard endpoint, so a bot can post the standings back into clan chat.

What is deliberately not automated

Nothing here reads, scripts or automates the game itself. Tools that log into your account or scrape the client put that account at risk, break with every game update, and are outside what this project will do. Capture starts from something you can already see: a screenshot, a message, a number a member reports.

5. Import history from a spreadsheet

Already keeping tallies in Excel, Google Sheets or a Discord bot export? Put them in a CSV with these columns and upload it on the Import CSV page (a Pro feature).

date,member,chest,quantity,source,note
2026-07-28,Aragorn,Gold Chest,3,clan,tournament
2026-07-28,Boromir,Silver Chest,5,event,
2026-07-29,Éowyn,Boss Chest,1,dungeon,first kill

• date — any date your server understands; YYYY-MM-DD is safest.
• member — matched case-insensitively. Unknown names are added to your roster automatically, so check your spelling before uploading.
• chest — must already exist on the Chest types page. Rows naming an unknown chest are skipped and listed back to you.
• quantity — a whole number, at least 1.
• source — one of clan, event, dungeon, battle, quest, shop, VIP, gift, other. Anything else becomes “other”.
• note — free text, optional.

A header row is detected and skipped. After the upload you get a count of what was imported and the reason for every skipped line. Import the same file twice and you get the entries twice — check the chest log before re-uploading.

Going the other way, Export CSV on the chest log and reports pages downloads exactly what your filters show, ready for a spreadsheet or your clan's records.

6. Read the reports

The dashboard

• Chests / Score / Entries / Active members — the totals for the period you picked.
• Chests per day — 30-day bar chart. Gaps mean nobody logged, which is worth knowing on its own.
• Leaderboard — top ten by score.
• By chest type — where the chests are actually coming from.
• Needs a nudge — active members with nothing logged in seven days.

Reports

Reports is the full picture for a period: the complete leaderboard with each member's last chest, totals per chest type, a breakdown per source, and the inactive list. Use the period presets (this month, last month, last 7 days, all time) or set a custom range for an event.

Print produces a clean page with no menus — good for screenshotting into clan chat. Export CSV gives you the raw rows.

Score = quantity × chest points, summed. If a total looks wrong, check the chest type's points first (step 2) — a single mis-set value moves the whole board.

Roles and access

Accounts are managed on the Team access page. Creating an account there sends the person their sign-in details; ask them to change the temporary password once they are in.

Removing access disables the account and unlinks it from the clan; the chests that person logged stay in the history. Every clan sees only its own data.

Plans and billing

The free plan runs a small clan comfortably. Pro lifts the member and monthly-entry limits and unlocks CSV import and export — see Pricing for the current numbers on this site.

• Only the clan owner can subscribe or cancel.
• Payment goes through PayPal. You approve a subscription in your own PayPal account, and it renews until you cancel it.
• Cancelling keeps Pro features until the end of the period you already paid for; after that the clan drops back to free. Your data is never deleted — limits just apply again.
• If a payment status looks stale, press Refresh status from PayPal on the subscription page.

Troubleshooting

A member is missing from the quick log

They are marked inactive, or not on the roster yet. Check Members.

A chest type is missing from the quick log

Show when logging chests is unticked for it on the Chest types page.

The leaderboard looks wrong

Check the period filter first, then the chest points. Score is quantity × points, so one wrong point value shifts everyone.

Someone was logged twice

Filter the chest log by member and date, then delete the duplicate. Officers can delete any entry.

“Your plan's limit has been reached”

The free plan caps members and entries per month. Remove unused members or upgrade — nothing already recorded is lost.

Export or import is locked

Both are Pro features on this site's default plans.

“Too many sign-in attempts”

Wrong passwords are rate-limited. Wait for the window to pass, use Forgot password?, or ask the site administrator to clear the lockout.

Where do I get an update package?

Run php bin/release.php in a checkout of the project — it writes the ZIP and manifest into dist/. Site administrators install it under Admin → Updates.

The site says it is under maintenance

The administrator is updating it. Try again in a few minutes.

The password reset email never arrives

Check spam, then ask your clan owner or the site administrator — small servers often need mail settings configured before they can send.

FAQ

Does this read my Total Battle account automatically?

No. There is no public API, and no plugin or bot is involved. You record what your clan sees. Never share your game credentials with any third-party tool.

Is it allowed alongside the game?

It is an ordinary website you type numbers into, like a spreadsheet or a Discord channel. It does not connect to, modify or automate the game in any way.

Can two clans share one installation?

Yes. Each clan is separate and only ever sees its own members, chests and reports.

Can I run more than one clan myself?

One account belongs to one clan. Use a second account (a different email address) for a second clan.

What if someone renames in the game?

Edit their member row and change the name. History follows the member, not the name.

Can members see each other's numbers?

Yes — the leaderboard and chest log are visible to everyone in the clan. That transparency is the point.

What happens to my data if I stop paying?

Nothing is deleted. The clan returns to the free plan's limits, and everything recorded stays readable.

Can I get my data out?

Yes — CSV export on the chest log and reports pages, covering whatever your filters show.

Still stuck? Email admin@surfanje.eu.

Independent clan tool. Not affiliated with, endorsed by or sponsored by the makers of Total Battle. Game names and trademarks belong to their owners.