ZnoteX

A complete website for your Open Tibia server.

Version 2.0.5 · Maintained by Open Games Community

Website · Source & releases · Themes · Plugins

About

ZnoteX is a full automatic account creator (AAC) and website for Open Tibia servers — account registration, character management, highscores, guilds, houses, a forum, a shop and an admin panel, all in one package. It is written in PHP with a simple procedural framework, so it is easy to read and easy to modify.

The original ZnoteX went unmaintained for roughly five years. This repository picks the project back up rather than starting over — we think it is the strongest foundation among the available Open Tibia AAC projects, and we intend to keep building on it.

Requirements

PHP 8.0 and older are not supported and will be refused at startup.

Optional: for e-mail verification and account recovery, download PHPMailer 6.x and extract it into the ZnoteX directory as a folder named PHPMailer.

Supported servers

Set $config['ServerEngine'] in config.php to match your server:

TFS 1.0 is not supported.

Canary notes — two-factor authentication is unavailable (Canary's account table has nowhere to store it), and the shop uses Znote's own points system rather than Canary coins.

Web server stacks

You need Apache (or nginx) + PHP 8.1+ + MySQL/MariaDB. On Windows, any of these bundles work — just make sure you grab a build that ships PHP 8.1 or newer.

On a Linux VPS or shared hosting you do not need any of these. Just set the hosting panel to PHP 8.1 or newer (8.3 / 8.4 recommended).

Installation

Docker (fastest way to try it)

git clone https://github.com/Open-Games-Community/ZnoteX.git
cd ZnoteX
cp .env.example .env
docker compose up -d

That's it — open http://localhost:8080. The stack brings up:

ZNOTE_SERVER_ENGINE in .env picks which game database gets imported on first boot, matching the same six choices the installer offers:

Set it in .env before the first docker compose up -d — the schema is only imported once, into a fresh database volume. To switch engines afterward, docker compose down -v (this wipes the database) and start again. config.local.php is generated automatically from docker-compose.yml's environment values on every container start — edit those instead of the file itself. Change ports or credentials in .env before the first start if the defaults collide with something else on your machine.

This environment is for trying ZnoteX or developing on it — every bundled game schema is a demo, not a real Tibia server. Point ZNOTE_DB_* at your actual server's database for production use.

The installer

Extract ZnoteX into your web directory and open /install/ in a browser. Six steps:

Import your OT server's schema first. ZnoteX reads accounts and players; it has never created them and will not pretend to. Step 2 refuses to continue until they exist — importing TFS/Canary's own schema.sql afterwards would overwrite what the installer is about to write.

Step 5 creates a real, working administrator: the account, a character on it, and the password hashed the way login.php expects on your engine. Step 6 puts that account name in page_admin_access, so you can reach /admin/ the moment the installer finishes. It writes to config.local.php, not config.php — see below — though a checkbox on the last step will write the admin name into config.php instead if you prefer.

When it is done, delete the install/ folder. It refuses to run again on its own (step 6 leaves a lock file), but there is no reason to leave it on a public server.

config.php and config.local.php

config.php holds every default and every comment. config.local.php holds only what is specific to this install — database credentials, engine, site name, admin names — and is included last, so it wins.

That split is what makes updating painless: a new ZnoteX release can ship a new config.php without touching your settings. Keep config.local.php out of version control.

Most other settings are editable from Admin Panel → Settings without opening a file at all.

Installing by hand

If you would rather not use the installer, or it cannot write the config file:

1. Import your OT server's schema, then SQL/znote_schema.sql, into the same database.
2. Create config.local.php next to config.php:

<?php
$config['sqlHost']     = '127.0.0.1';
$config['sqlUser']     = 'your_db_user';
$config['sqlPassword'] = 'your_db_password';
$config['sqlDatabase'] = 'your_db_name';

$config['ServerEngine'] = 'TFS_10';   // see "Supported servers" above
$config['site_title']   = 'My Server';
$config['site_url']     = 'https://example.com/';
$config['page_admin_access'] = array('YourAccountName');

3. Make engine/cache/ writable by the web server.
4. Open the site. If anything is misconfigured, the page tells you what to fix.

Memory cache (APCu)

ZnoteX caches highscores, news and similar pages. It can keep that cache in files under engine/cache/, or in RAM via the APCu extension.

config.php ships with 'memory' => true, so a fresh install without APCu stops on every cached page with "Configuration error! APCu is not enabled." If you see that, you have two choices — install APCu, or switch to the file cache by putting this in config.local.php:

$config['cache']['memory'] = false;

The file cache needs no extension, works everywhere, and only requires engine/cache/ to be writable.

APCu is optional. It saves a few disk reads per request. On a local or low-traffic server you will not notice the difference — it is worth installing once you have real player traffic.

Installing APCu on Windows

Download from pecl.php.net/package/APCu/5.1.28 and click the DLL link. The build must match your PHP exactly — check yours with php -i or phpinfo():

Uniform Server is thread-safe, so with PHP 8.3 it needs php_apcu-5.1.28-8.3-ts-vs16-x64.zip. Most Windows guides say nts because that is what other stacks use — picking the wrong one means the DLL is ignored with no error.

1. Copy php_apcu.dll from the zip into your PHP extensions (or ext) folder — the path in extension_dir.
2. Add to your php.ini:

   extension=apcu
   apc.enabled=1

   Uniform Server has no single php.ini: the web server reads php_production.ini or php_development.ini from core/php83/ depending on the mode it is running in.

3. Restart Apache, then set memory to true.

On Linux, pecl install apcu or your distribution's php-apcu package.

Already have players?

Open /special/ to convert an existing OT database for ZnoteX.

Coming from another AAC instead? Admin Panel → Settings → Convert SQL takes a MyAAC or Gesior2012 database dump and gives you back a ZnoteX conversion SQL — accounts, players, news, gallery and the rest. Tables ZnoteX has no equivalent for are preserved rather than dropped.

Upgrading

Use Admin Panel → Update (see below) — it handles this automatically. If you would rather do it by hand, replace everything except config.local.php, layouts/, plugins/ and engine/cache/, apply any new file in SQL/migrations/, and check Admin Panel → Plugins in case a plugin has an update waiting.

Update ZnoteX

Admin Panel → Update checks, verifies and installs new ZnoteX releases directly from GitHub — no re-running the installer, no manually copying files. It downloads the release, checks its digital signature and per-file checksums, runs a pre-installation check (PHP version, extensions, disk space, writable paths, local modifications), backs up every file it is about to touch, then installs. If anything goes wrong afterwards, Restore latest file backup puts the previous version straight back.

Features

Admin Control Panel

Everything below lives at /admin/. Access is controlled by $config['page_admin_access'] in config.php. The panel is grouped the way the sidebar is.

Overview

• Search — every page and every setting, by name or by what it does. Typing download reaches the client URL fields under Settings, not just a page whose title happens to match.
• Dashboard — server and community at a glance: environment, recent accounts and characters, top point balances, open queues.
• Visitors — traffic ZnoteX has been recording all along.

Content

• News — write, edit and remove front-page articles, with a BBCode editor.
• Changelog — the entries shown on the public changelog page.
• Gallery — moderate player screenshot submissions.
• Menus — build the site navigation without touching a template. A top-level entry is a category: a heading that opens its children rather than a link of its own, so it needs no URL.

Players

• Accounts — search an account, see its characters, points and history.
• Player Tools — punish, move, rename and maintain characters and their accounts.
• Character Skills — read and rewrite level, vocation, health, mana and skills.

Server Info

Your server's own files, uploaded once here instead of pasted into public pages.

• Server Information — upload config.lua, stages.xml, items.xml, spells.xml and your monster folder. Each one is parsed on upload and published to the page that uses it: serverinfo.php, items.php, spells.php, creatures.php and monster_loot.php. For the monsters, monsters.xml alone gives you the names; a .zip of data/monster/ also gives health, experience, speed and race.
• Minimap — import the .otmm your OTClient/OTCv8 writes. ZnoteX converts it into map tiles and shows a pan/zoom viewer with floor arrows on Server Information. Nothing is rendered at all unless a minimap is imported.

config.lua is parsed on upload and never written to disk — it carries your MySQL password, and engine/XML/ is served by the web server. Only the whitelisted settings are kept.

Economy

• Shop Manager — add, preview, hide and remove shop offers. They live in znote_shop_offers now, not in $config['shop_offers'].
• Payments — gateways, credentials and the point packages players can buy.
• Shop Pending / History — pending deliveries and completed purchases.
• Character Auctions — ongoing, unclaimed and completed character sales.

Support

• Bug Reports — triage in-game reports, reward reporters, publish changelogs.
• Helpdesk — answer, close and delete support tickets.
• Feedback Board — forum threads awaiting a staff reply.

Settings

• Layout — switch theme, edit its options, browse and install themes from a repository.
• Plugins — install, update, enable and disable what is in plugins/.
• Settings — most of config.php, from the browser.
• Convert SQL — upload a MyAAC or Gesior2012 database dump and download a ZnoteX conversion SQL. Tables ZnoteX has no equivalent for are kept rather than dropped, and each converted row is mapped back to the row it came from, so a conversion can be traced and re-run.

Themes

Every theme is a folder under layouts/. A theme is plain HTML and CSS — the PHP stays in ZnoteX, so editing one is editing markup, not untangling a template engine. layouts/default/ is the theme that ships; layouts/_example/ is a documented skeleton to copy.

Everything below is in Admin Panel → Layouts.

Switching. Every installed theme is listed with a screenshot, 12 per page. Click one to make it active. It applies to the public site only — the admin panel never changes.

Options. A theme declares its own settings in theme.json — a background image, its logos, social links, a tagline, a colour, an editable line of footer text. They appear under Options on that theme's card and are stored in the database, so you change them from the panel instead of editing the theme's files, and updating the theme cannot lose them.

An option of type image shows the current picture, its path, and an upload field. Uploads land in engine/img/theme/<theme>/, deliberately outside layouts/, so replacing or re-extracting a theme leaves them alone. An image that only exists inside a static stylesheet is reachable too: the option declares the CSS rule that places it and ZnoteX writes that into the page head, so no theme file has to change.

The footer option is one line of your own, rendered above the credits — the copyright and engine credits stay in the theme's files on purpose, not in the panel.

Installing one. Two ways:

• Manually — unzip the theme folder into layouts/. It appears on the next page load.
• From a repository — press Browse themes to list themes hosted elsewhere and install one with a button.

The repository is configured by $config['layout_repository'] in config.php, and points at this project's layouts branch by default. Downloads are refused unless the URL is https and its host is on allowed_hosts — a theme is code that runs on your server, so only point it at a repository you trust. The tooling that packages themes and regenerates a catalogue lives on the layouts branch, alongside the archives themselves.

Child themes. A theme can name another as its parent and override only the files it wants. The rest falls through to the parent, so a colour change is one stylesheet rather than a fork — and the parent can still be updated underneath it.

See layouts/README.md for the full contract.

Plugins

A plugin is a folder under plugins/ that adds public pages, admin pages, database tables and behaviour without editing a single ZnoteX file — so an update never costs you your work.

plugins/my_plugin/
  plugin.json        name, version, author, description   [required]
  plugin.php         registers hooks
  pages/<page>.php   public page at page.php?plugin=my_plugin&p=<page>
  admin/<mod>.php    admin page, listed in the sidebar
  install.sql        tables, created on install
  assets/            css, js, images

Everything below is in Admin Panel → Plugins.

Installing one. Download it, unzip the folder into plugins/, reload the panel, press Install. That runs its install.sql and switches it on. ZnoteX never downloads a plugin by itself: a plugin is PHP that runs on every page of your site, so putting the files there stays a deliberate act rather than a button.

Updating one. Replace the folder with the newer version. If its plugin.json carries a higher version than the one recorded at install time, an Update button appears and applies whatever the new version needs.

Removing one. Disable stops a plugin; Uninstall also forgets its version. Neither ever drops a table — removing a plugin for good means deleting its folder and dropping its tables yourself.

A plugin runs with the same privileges as the rest of the site, and nothing sandboxes it. Install plugins whose author you know or whose code you have read.

plugins/shop_coupons/ is a working example — redeemable codes that either credit shop points or take a percentage off the next purchase — and is commented as a tutorial. See plugins/README.md for the contract and the list of hooks.

Contributing

Issues and pull requests are welcome at github.com/Open-Games-Community/ZnoteX.

License

See LICENSE. Original ZnoteAAC modified by Alex renamed to ZnoteX; layout by Blackwolf (Snavy).