Getting started

Setting up the panel, roles, the audit log, search and other basics.

Two halves of one system:

  • laravel-app/ – staff web panel and REST/JSON API (Laravel 13, Blade + Tailwind CSS 4 styled on GOV.UK Design System patterns).
  • skript/ – the Minecraft side for 1.8.9 / Skript 2.6.5-for-1.8 + skript-reflect. It polls the API for actions, syncs sessions and player data, and keeps working when the API is down.

Servers never hold a socket open to the panel. The panel writes actions into action_queues. Each server polls every 5 seconds with a bearer token, runs what it gets, and acknowledges each action.

 Staff ──► Panel (web) ──► action_queues ◄── GET /queue (every 5s) ── Minecraft server
                │                         ── POST /queue/ack ──────►      (Skript)
                ├── Discord webhooks (queued jobs)
                └── SMTP (ban emails, invites, password resets)

Setup #

cd laravel-app
composer install
npm install
npm run build
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan network:create-owner you@example.com "Your Name"

To use MySQL, set DB_CONNECTION=mysql and fill in the DB_* values in .env. Development uses SQLite.

Cron #

Cron. In production, add two cron jobs, both running every minute (* * * * *). In HestiaCP, use Cron jobs → Add. Change the path to wherever the app is deployed:

cd /home/USER/web/portal.neutine.net/public_html && /usr/bin/php8.4 artisan schedule:run >> /dev/null 2>&1
cd /home/USER/web/portal.neutine.net/public_html && /usr/bin/php8.4 artisan queue:work --queue=urgent,default --stop-when-empty --max-time=55 >> /dev/null 2>&1
  • schedule:run runs every task in the task manager. It stays alive for the whole minute so the 15-second server sweep still fires four times a minute.
  • queue:work sends Discord messages and emails. --queue=urgent,default makes it take the urgent queue first: retries of in-game /otp codes go there. The codes themselves are sent straight away, without waiting for the worker.

The staff Tasks page (permission tasks.manage) shows these lines with this server's real paths filled in. It also warns if either job isn't running.

Task manager #

Task manager (/tasks): lists each scheduled task with its schedule, last run, result, duration and failures in the last 24 hours. Staff can run a task now, or pause and resume it. The page also shows recent run history with output, queue health, and failed jobs with retry and delete. Every action is audited. Tasks are defined in app/Support/TaskRegistry.php, so the scheduler and the page always match.

Run the tests (46 feature tests, covering the API flow, RBAC, the portal, friends, recovery and the task manager):

php artisan test

History #

History (/history, permission servers.view): player counts over 24 hours to a year for the network or one group, region or server, with peaks, unique players, sessions, the busiest hours of the week and a per-server breakdown. It also predicts the next 7 days. The record-player-counts task saves a count for each enabled server every 5 minutes, and rows are kept for 400 days. Its first run rebuilds the last 90 days from player sessions, so predictions start straight away if there are at least 48 hours of sessions.

Predictions use the same hour of the week over the last 6 weeks, with recent weeks counting most. With under 14 days of history they use the same hour of the day instead. The figure is then scaled by how the last 6 hours compare with normal, and that effect fades over the following hours. The page shows how far yesterday's prediction was from what really happened. The dashboard shows the last and next 24 hours for the whole network.

Legal pages (/manage/legal, permission legal.manage): Terms of Service, Privacy Policy, Cookie Policy, Refund Policy and Community Guidelines, linked at the bottom of every page. Default text lives in resources/legal/*.md and describes what the panel does. Staff fill in who runs the network, a contact email, the governing law and the minimum age, and those details fill {operator}, {email}, {country} and {minimum_age} in the text. Editing a page saves a copy, and "Reset to the default text" removes it. Have someone qualified check the text. If you change what the network collects or who it shares data with, update the Privacy Policy.

Roles and permissions #

Permissions are defined in config/permissions.php. Each one is a Laravel Gate ability, so routes use can:players.edit and views use @can('players.edit'). Navigation items, tabs, buttons and form options only appear when the user has the matching permission. The server checks every route again.

Permission Allows
dashboard.view Dashboard
players.view / players.view_ips / players.view_messages / players.edit Player search and profile, IPs and alt accounts, chat/PM logs, email and notes
ranks.manage Queue a rank change
punishments.view / .kick / .warn / .mute / .ban / .revoke Punishment history and each action, checked per type
broadcasts.send Global or per-server announcements
servers.view / servers.manage Servers and queue; registering servers, rotating keys, retry/cancel
customitems.manage Register custom items that servers and scripts can use
rarity.manage Rarity: which items have a rarity (the mode and the list), how each tier looks and where the rarity line shows
custommessages.manage Create the join, quit and death messages players can choose
textmojis.manage Add, edit and delete chat textmojis
inbox.send Send a message to a player's in-game inbox, under your name or as Anonymous
tag.manage Tag settings, skills, maps and the weekly leaderboard
store.manage Store (Tebex): settings, what packages give, payments and refunds
whitelist.manage Turn whitelists on and off and choose who can still join
jobs.manage Jobs: create jobs, their tasks, levels, requirements and quests
console.view / console.command A server's live console; running console commands from it (owners only by default)
console.grant Give or remove console access for specific staff accounts, no more than their own role has (Servers → Console access)
accounts.impersonate Sign in as another account (not an owner) from Accounts, and return (owners only by default)
settings.manage Discord webhooks, SMTP, the site's look (Settings → Appearance: Onyx, Standard or Matte glass)
staff.manage / roles.manage Invites, role assignment, deactivation; custom roles
audit.view Audit log

Default roles: Owner (*), Administrator, Moderator and Helper. Only an owner can grant or edit owner-level access. Custom roles can never receive *.

Staff accounts are invite-only (Staff → Invite). If SMTP isn't configured yet, the panel shows the one-time link so you can send it yourself. Password reset uses Laravel's password broker. New passwords must be at least 12 characters and are checked against known breaches.

Markdown #

Longer texts staff write for the website use Markdown: bold, italic, - lists, [links](https://...), headings, quotes, tables and code. A single new line is kept. This covers:

  • store package descriptions
  • update posts
  • site announcements
  • feedback form introductions
  • staff application positions (description and requirements)
  • network package notes
  • deployment instructions

HTML typed in is shown as text, javascript: links are dropped, and links to other sites open in a new tab. Text that also shows in-game (quests, events, skills...) stays plain, since Minecraft can't show Markdown.

Audit log #

AuditLogger records every staff action: sign-ins, punishments, revocations, player edits, rank changes, broadcasts, server and key changes, queue retries, settings, staff and role changes. Each entry stores the actor, IP address, user agent and a UTC timestamp. You can filter by staff member, category, IP and date range. Entries can't be edited or deleted from the panel. Secrets are never logged: the log notes that an SMTP password or an email changed, not the value. Non-punishment actions are also sent to Discord webhooks subscribed to staff_actions.

If the panel runs behind a reverse proxy, set TRUSTED_PROXIES so the log records real client IPs.

Navigation. The menu is on the left, grouped (Players, Community, Game, Servers, Administration for staff; My account, Play, Pit, Social, Community for players). New pages only need a line in app/Support/Navigation.php, and items are hidden when the user lacks the permission.

Accounts #

Accounts (/accounts, permission accounts.manage): every web account, staff and players. Create an account (with or without a password: without one the person gets a reset link), change roles, deactivate, link or unlink a Minecraft account, send a password reset, and manually verify an account. Only owners can create owners or change an owner. Staff invitations can be resent from Staff; resending makes a fresh 7-day link.

Sign in as #

Sign in as (permission accounts.impersonate, owners only by default): on Accounts, open an account and choose Sign in as … to see the panel or portal exactly as they do. An orange bar at the top shows whose account you're on, with Return to my account. Owners can't be signed in as, and you can't sign in as a third person from someone else's account. Everything done meanwhile is in the audit log under your name ("You (as Them)"), as are the start and the return.

Authentication #

Authentication. Sign-in is the app's own (sessions, hashed passwords, invites, resets, Minecraft sign-in and recovery); there is no third-party login to switch to.

Sensitive data #

Sensitive data. Emails, IP addresses and Discord IDs are blurred on staff and portal pages until hovered, tapped or tabbed to, so they don't show on a shared screen. They're still in the page, so this isn't access control: players.view_ips still decides who gets IPs at all.

Search. The box at the top of every signed-in page (click it, start typing in it, or Ctrl + K) opens a search window. On this page comes first: headings, fields, buttons, table cells and text on the page being looked at; clicking one opens any folded section it's in, scrolls to it and flashes it. Then the rest of the panel, grouped. All results opens the full list at /search, which also works without JavaScript. Every word typed must match. Staff also get Settings: every game rule, found by its name, its description or its key (afk finds Anti-AFK and the AFK rules), once per category with its value there ("Game rule · Survival: On") and linking straight to that field on the category's page; game mechanics; and island settings, each only with the permission that edits them. Staff with Help get Help: the documentation's sections, best match first. A link to a field (#rules-anti_afk) opens the section it's in and flashes it. Besides those, it finds menu pages, plus records in app/Services/AppSearch.php: staff get players, accounts, reports, punishments, servers, crews, quests, badges, pets, jobs, shop items, events and update posts, each only with the permission that opens them. Players get public profiles, active quests, badges that aren't secret, pets, events, published updates and feedback forms.

Getting started tutorials #

Getting started tutorials (app/Support/Tutorials.php). The staff dashboard and the player overview each have a guided tour that starts once per account, shows only steps for pages that person can open, and can be restarted from Getting started on that page, which also lists the steps as plain text. Finishing or skipping is remembered on the account (users.tutorials_seen). Sign in as never starts or uses up someone else's tour. To point a step at a menu link, use its route name as the target; anything else needs a data-tour attribute.

Domains #

Domains. Point both portal.neutine.net and staff.neutine.net at this app and set APP_URL=https://portal.neutine.net. The Skript api_url can keep using staff.neutine.net/api/v1.

Account recovery and in-game sign-in #

Account recovery and in-game sign-in. These work for player accounts only. Staff must use their password, so a stolen Minecraft account can't open the staff panel.

  • Sign in with Minecraft (/login/minecraft): the player enters their username and gets a 6-character code. In-game, /verify CODE shows what the request is for, its approximate IP and browser. /verify CODE confirm approves it, and the browser signs in.
  • Temporary access (players without an email): a player who has joined the network but has no portal account uses Sign in with Minecraft the same way and gets an hour of limited access. It's approved with /verify only while they're signed in on the server (in-game sign-in on and a live session; with in-game sign-in off for the network, nobody can get it). The hour starts when the browser signs in; after it they're signed out and get a new code from in-game. Temporary accounts (users.is_temporary, an unusable …@temporary.invalid address and password, never staff) can only use their island (not resetting it or paying for a subscription), viewing and making a crew (no edits), the dungeons page, the account page and signing out (User::TEMPORARY_ROUTES, enforced by LimitTemporaryAccess), and their portal menu only shows those pages (Home, Island, Dungeons, My crew); anything else sends them back to their island. Linking a real account with an email later replaces the temporary one. Each grant is in the audit log (portal.temporary_access). /access in-game is the quicker way: a player signed in on the server gets a clickable link that signs them in with the same temporary access (/access/{token}; it works once, for 5 minutes, and a new /access replaces the last link). Players with a real portal account are told to sign in normally.
  • Recover your account (/recover): the same in-game approval, then the player chooses a new password. This works even if they've lost access to their email, which they can then change in settings.
  • In-game: /account shows the linked email (masked). /account resetpassword emails a normal reset link.
  • Codes are hashed, single-use, tied to one Minecraft account, and expire after 5 minutes.

New lines in in-game text #

New lines in in-game text: anything typed on the panel that players see (skill, job, pet, loadout and map descriptions, broadcasts, custom command replies, kick and whitelist messages, quest and job messages...) can break onto a new line with %nl%, %newline%, {nl}, <br> or , or by pressing Enter in the bigger text boxes. Item lore splits into separate lines and keeps its colour. Titles and the action bar show one line. Scripts can use the same: Net_Color and Net_Breaks turn them into line breaks, and Net_Lore(lines) / Net_LoreAdd(list, line) build lore from them (core/Support/Compat.sk).

Copy and paste as JSON #

Copy as JSON / Paste JSON (resources/js/json-config.js): the create and edit forms for game content have a bar at the top. Bosses, boss attacks, elite mobs, quests, crew quests, story lines, custom items, recipes, artifacts, blessings, jobs, classes and class skills, weapon skills, enchants, Pit skills, Tag maps and skills, particle effects, kill effects, sounds, pets, loadouts, ranks, commands, custom messages, repeating broadcasts, events, achievements, leaderboards, vote sites, feedback forms and server groups all have it.

  • Copy as JSON puts the form as it is now on the clipboard, as {"neutine": "boss", "version": 1, "data": {...}}.
  • Paste JSON fills the form from that, on this panel or another, and recreates its rows (rewards, quest steps and their objectives). Lists that were empty are emptied. Nothing is saved until you press Save, so it goes through the same checks as typing it in.
  • The JSON is made from the form's own fields, so it always matches what the form saves.
  • A copy of one kind (a boss) can't be pasted into another (a quest).
  • Fields the form doesn't have are listed and left out.
  • Left out of copies: the CSRF token, files, passwords, disabled fields and fields marked data-json-skip. A key that can't be changed once it's made (bosses, weapon skills, enchants) is still copied from the edit form (data-json-key on the <form>), so the copy can be imported.

To add it to a form: data-json="kind" on its <form>.

Import JSON #

Import JSON (Administration > Import JSON, App\Support\JsonImport, JsonImportController, component x-json-import) adds content from those copies, many at once: .json files (up to 20, 2 MB each) or pasted text, each holding one copy or a list of them ([{...}, {...}]), of any kinds the user can add. The same box is on the Bosses, boss edit (special attacks), Loadouts and shop (shop items and presets, into the group shown), Custom items, Artifacts, Combat, Recipes, Particle effects, Kill and death effects, Pets, Blessings, Badges and Sounds pages.

  • Only valid copies are added. Each one goes through its create form's own save action, so it gets the same checks, permission and audit log entry as typing it in, inside a transaction: if anything is wrong (a check fails, the key is taken, a custom item or particle effect it names doesn't exist, the action refuses, like a boss's 13th attack) nothing of it is kept. It's skipped and listed with the reasons; the others still go in.
  • Copies that aren't valid JSON, have no "neutine" and "data", are another version, or are a kind that can't be imported (elite mobs are only edited) are skipped the same way.
  • Order: custom items, particle effects, sounds, server groups and ranks go first, then skills and enchants, then the rest (JsonImport::KINDS), so one import can hold a particle effect and the boss that uses it. A custom item gets a new ID on the panel it's imported to, so copies naming one by ID need that ID changed.
  • Boss attacks need the boss, and shop items and preset loadouts need the server group: the page gives them (the Import JSON page has a dropdown for each), or the copy can say "boss": "key" / "group": id or name next to "data".
  • Importing never publishes: a quest copy's publish is dropped.
  • Up to 200 copies at a time; one audit log entry lists what was added and skipped.
  • To make a kind importable: its data-json kind and create route in JsonImport::KINDS.
  • Accepted fields and values (component x-json-guide, App\Support\JsonImportGuide): a folded guide inside every import box, one section per kind the page imports (every kind you can add on the Import JSON page). Each field of "data" is listed with its type (text, whole number, number, true or false, list, choice), whether it's needed (or needed only when another field is set), its limits (length, range, number of rows), its default (tick boxes, which are off when left out unless it says otherwise) and its accepted values, with a short example to start from. Nothing in it is written by hand, so it can't drift from what an import accepts: the rules are read from the create form's own save action (started with an empty request and stopped at its first validate(), before anything is saved), and the values come from those rules as they are now: shop categories and enchantments, server groups and servers, custom item IDs, particle effects, rarity tiers, pet ability types and so on, with labels where the list has them. Material and icon fields list the materials the panel accepts (ItemMaterials). Long lists scroll, with a filter box. Rows that a form checks in its own code (boss drops, rewards, quest steps) say so: Copy as JSON on the form shows their shape.

Sorting lists #

Sorting lists (resources/js/app.js, every table.govuk-table): click a column heading to sort the rows by it: once for ascending, again for descending, a third time for the page's own order. An arrow shows the direction and the heading gets aria-sort for screen readers. Numbers, amounts like 1.5k or 2M, percentages, times like 1h 30m or 2 days ago, and dates sort by value; anything else alphabetically. Empty cells (blank, –, Never) stay at the bottom. It only sorts the rows on the page, so on a list with pages it sorts the current page, not the whole list. Nothing is remembered: refreshing shows the default order again. Columns with no visible heading (buttons, tick boxes) can't be sorted, and tables with merged cells or drag-to-order are left alone. data-sort-value on a cell sorts by that instead of its text; data-no-sort on a table or heading turns it off.

Bulk actions #

Bulk actions (App\Support\BulkActions, BulkActionController, components x-bulk.bar, x-bulk.all, x-bulk.check): most lists have a tick box on each row and a bar above them ("With the ticked quests...", Apply, Tick all). Staff lists can delete, and where a list has an on/off switch, turn on or off (Show / Hide, Open / Close...; quests have Publish changes and Take off servers instead, see quests.md). On the portal, players can delete several homes, loadouts, friends or API keys, and share homes with a player, their crew or friends (with an end time) or stop sharing. Deleting shows the records and asks first. Each record goes through the same code as its own button, so permissions, ownership, audit log entries and clean-up are unchanged; records it refuses (the Owner role, someone else's home) are listed and the rest still happen. Turning on or off is one audit log entry and also republishes Script editor projects. Up to 500 at a time; the list needs the same permission as deleting one. To add a list: an entry in BulkActions::definitions() (its delete route and on/off column), then <x-bulk.bar for="key" /> above the table, <x-bulk.all for="key" /> as the first header cell and <x-bulk.check for="key" :id="$x->getRouteKey()" /> as each row's first cell (:cell="false" on cards).

Two-factor authentication #

Web accounts can turn on authenticator-app 2FA (TOTP, RFC 6238: SHA-1, 6 digits, 30 seconds) under Account > Settings. The code is in App\Support\Totp, App\Services\TwoFactorService and App\Support\PendingLogin. QR codes come from bacon/bacon-qr-code as inline SVG, because PHP has no bundled QR encoder and that package needs no gd or imagick.

  • Storage: the secret is encrypted with APP_KEY and recovery codes are SHA-256 hashes, on the users row, hidden from serialisation. Changing APP_KEY without keeping the old one in APP_PREVIOUS_KEYS makes secrets unreadable, and those users then need a staff reset or a recovery code.
  • Replay: users.two_factor_last_step records the newest 30-second window used, and a code must be for a newer one.
  • Throttle: code entry allows 5 tries a minute and 30 an hour, per account.
  • Audit log: auth.two_factor_enabled, auth.two_factor_disabled, auth.two_factor_recovery_used, auth.two_factor_recovery_regenerated and accounts.two_factor_reset.

How each way in treats it:

Route With 2FA on
Password (/login) Goes to /two-factor. Signed out on every route until the code is accepted. "Keep me signed in" only applies after that.
Sign in with Minecraft (/login/minecraft) Same. In-game approval replaces the password, not the code.
Account recovery (/recover) The new password is saved, then /two-factor. 2FA stays on.
Password reset Doesn't sign in. The next sign-in asks for a code. 2FA stays on.
Staff "Sign in as" No code: the staff member is signed in and audited, owners can't be signed in as, and they can't change the account's 2FA. Returning to their own account needs no code.
Registration and staff invitations Always a new account, so there is no 2FA yet.

Someone who has lost their app and recovery codes needs a reset from staff with accounts.manage, on the Accounts page. Only an owner can reset an owner, and nobody can reset themselves there. Settings > Security can require 2FA for staff: staff without it can only set it up or sign out.

Hiatus #

Hiatus (Overview → Hiatus, /hiatus, every staff member). Going away for a while? Set a start date (today or later, within a year), an optional return date and a note. Every other active staff member gets an email, and Discord webhooks ticked for Staff hiatus or Staff actions get a post; the same happens when you come back early ("Back already?"). Each staff member has one open hiatus at a time. The page lists who is away, who is going away soon and who came back in the last 30 days, and the dashboard shows who is away.

Staff payroll #

Payroll (Administration → Payroll, /manage/payroll, permission payroll.manage). Pay staff on a schedule in global coins, items in /inbox or a rank for some days. Staff are paid to the Minecraft account linked to their panel account.

  • Pay plans. Each plan pays either everyone with a role or one staff member, every week (on a chosen weekday; weeks run Monday to Sunday) or every month (on day 1 to 28). It can give any mix of: global coins (straight to their balance, in the coin history as "Staff pay"), items sent as one /inbox reward to claim in-game, and a rank for a number of days. The rank time is added on to what they have left, so a monthly plan with 30 days keeps it going; someone who already has the rank for good keeps it for good. A staff member covered by more than one plan (their role's and their own) is paid by each. Turning a plan off stops it paying but keeps its history; changes apply from the next payment.
  • Pay day. The network:payroll scheduled task (Scheduled tasks → payroll, hourly) pays everyone still unpaid for the current week or month once its pay day has started (from midnight, the panel's time zone). Each payment or skip is saved once per plan, staff member and week or month, so running it again, two runs at once or a "Pay now" earlier in the week never pays anyone twice.
  • Hiatus. Staff on hiatus when the task reaches them are skipped for that week or month (shown as "On hiatus"). Coming back before it ends doesn't pay that period; the next one is paid as usual.
  • No linked account. Staff without a linked Minecraft account aren't paid or skipped: they wait, and the next run in that period pays them once they've linked one.
  • Pay now and skip. A plan's page lists who it covers and where each stands this period. Pay now pays one staff member straight away (also before the pay day, and also while on hiatus, since you chose to); Pay everyone now does the scheduled run for that plan by hand (hiatus still skips). Skip leaves someone out of this period, with an optional reason; Undo skip lets the next run (or Pay now) pay them. Payments can't be undone: take coins back on the player's page, and ranks on Ranks.
  • Telling staff. Each payment sends the staff member a notification (in-game straight away if they're online, otherwise when they next join, and on the portal) listing what they got. Items also get the usual "a reward is waiting" notice, and a rank its rank notice.
  • History. Payout history lists every payment and skip, newest first, filterable by staff member, with what was given at the time. Creating, changing and deleting plans, paying, skipping and undoing a skip by hand go in the audit log (payroll.*).