chore: harden php8 compatibility, optimize installer/croppers, and refresh docs/admin ux

2026-08-23 11:37:14 +00:00 · 2026-03-14 16:50:27 -03:00
parent 8a91e89644
commit a0ef06a35f
29 changed files with 871 additions and 418 deletions
@@ -1,97 +1,156 @@
-[![Code Triagers Badge](https://www.codetriage.com/shadowss/travianz/badges/users.svg)](https://www.codetriage.com/shadowss/travianz)
+# TravianZ
+
 [![Maintenance](https://img.shields.io/maintenance/yes/2025.svg)](https://github.com/Shadowss/TravianZ)
 [![GitHub Release](https://img.shields.io/github/release/Shadowss/TravianZ/all.svg)](https://github.com/Shadowss/TravianZ)
-[![Github All Releases](https://img.shields.io/github/downloads/Shadowss/TravianZ/total.svg)](https://github.com/Shadowss/TravianZ)
 [![GitHub contributors](https://img.shields.io/github/contributors/Shadowss/TravianZ.svg)](https://github.com/Shadowss/TravianZ)
 [![license](https://img.shields.io/github/license/Shadowss/TravianZ.svg)](https://github.com/Shadowss/TravianZ)
-[![GitHub last commit](https://img.shields.io/github/last-commit/Shadowss/TravianZ.svg)](https://github.com/Shadowss/TravianZ)
-[![Proudly Coded in PHPStorm](https://img.shields.io/badge/coded%20in-PHPStorm-BD5CF3.svg)](https://www.jetbrains.com/buy/opensource/?product=phpstorm)
-[![Join the chat at https://gitter.im/TravianZ-V8/Lobby](https://badges.gitter.im/TravianZ-V8/Lobby.svg)](https://gitter.im/TravianZ-V8/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Watch how this was made on YouTube](https://img.shields.io/badge/The%20making%20of...-YouTube-FF0000.svg)](https://www.youtube.com/watch?v=1XiHhpGUmQg&list=PLzV5avt1FFHorlIeoL9YX0pdb9bj-FO84)
-======
-[![GitHub forks](https://img.shields.io/github/forks/Shadowss/TravianZ.svg?style=social&label=Fork)](https://github.com/Shadowss/TravianZ)
-[![GitHub stars](https://img.shields.io/github/stars/Shadowss/TravianZ.svg?style=social&label=Stars)](https://github.com/Shadowss/TravianZ)
-[![GitHub watchers](https://img.shields.io/github/watchers/Shadowss/TravianZ.svg?style=social&label=Watch)](https://github.com/Shadowss/TravianZ)
-[![GitHub followers](https://img.shields.io/github/followers/Shadowss.svg?style=social&label=Follow)](https://github.com/Shadowss/TravianZ)
-[![Twitter URL](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/cata7007)
-======

-TravianZ Version **v.8.3.5** - BETA 1
-======
-**Note:** this game is still in a pre-release state, although at this point it is very playable, tested and found to be fairly stable
+TravianZ is an open-source browser strategy game inspired by classic Travian-like gameplay.

-**WARNING:** please note that ***this is in no way an upgrade*** from the old 8.3.2 version, so please ***do not try to just copy your files over***,
-since the installer logic has changed and you would just crash your old version
+This repository currently targets modern local/server setups with PHP 8.x and MariaDB.

-**Docker Quick Start:**
+## Project Status

-Get up and running quickly with Docker:
+- Version line: `v8.3.5` (legacy naming)
+- Stability: playable and actively maintained
+- Migration note: this is not a drop-in upgrade over older `8.3.2` deployments
+
+If you are upgrading from an older installation, do a fresh install and migrate data carefully.
+
+## Quick Start (Docker)

 ```bash
-# Clone the repository
 git clone https://github.com/Shadowss/TravianZ.git
 cd TravianZ
-
-# Copy environment file
 cp .env.example .env
-
-# Start containers
-docker-compose up -d
-
-# Open browser to http://localhost:8080/install
+docker compose up -d
 ```

-For detailed Docker setup instructions, see [DOCKER_README.md](DOCKER_README.md)
+Then open:

-**Quick links:**
-* [Download and Updates](https://github.com/Shadowss/TravianZ) &raquo;&raquo; https://github.com/Shadowss/TravianZ
-* [Wiki](https://github.com/Shadowss/TravianZ/wiki)
-* [Game Mechanics](http://travian.wikia.com/wiki/Travian_Wiki)
-* [The Making Of](https://www.youtube.com/watch?v=1XiHhpGUmQg&list=PLzV5avt1FFHorlIeoL9YX0pdb9bj-FO84) - YouTube Videos about this project
-* [Donate to TravianZ](https://www.paypal.me/cata7007)
+- `http://localhost:8080/install`

-**Minimum requirements:**
-* [PHP](http://php.net/) 7.0.0+
-* [MySQL Community Server](https://dev.mysql.com/downloads/mysql/) 5.5+
-  * or alternatively, [MariaDB](https://downloads.mariadb.org/) 5.5+
- * Runs fine on Ubuntu 20, Apache2 2.4, MySQL Server 8.0 and PHP 7.4
+Detailed container guide: [DOCKER_README.md](DOCKER_README.md)

-**Dedicated or shared hosting?**
+## System Requirements

-We *strongly* recommend using a ***dedicated hosting*** for this game. Big Travian servers used to host 
-thousands of players and the original servers still had about 300ms page display time. The legacy code 
-in this clone (which was created in 2013) is right now doing about **400 MySQL queries** (questions 
-to the database) per single page refresh - which is usually well beyond what most shared hostings can support 
-with a big enough player base.
+Recommended:

-**Support & Bug reports**
+- PHP `8.3+`
+- MariaDB `latest stable` (or MySQL-compatible server)
+- Apache or Nginx with PHP support
+- Linux server with enough CPU/RAM for your expected player count

-We are usually available to chat at our [Gitter channel](https://gitter.im/TravianZ-V8/Lobby), if you like to ask 
-any questions or just talk to the developers about how great their day is today :) As for bug reports, please use 
-the [Issues tab](https://github.com/Shadowss/TravianZ/issues) and create new issue, whether it's an error in game 
-or you have a feature request to be included in the play.
+Notes:

-**The team**
-* [Shadowss](https://github.com/Shadowss) - project owner and an occasional developer / tester
-* [lietuvis10](https://github.com/lietuvis10) - active developer
-* [iopietro](https://github.com/iopietro) - alumni developer
-* [AL-Kateb](https://github.com/AL-Kateb) - alumni developer
-* [martinambrus](https://github.com/martinambrus) - alumni developer
-* [Vladyslav](https://github.com/velhbxtyrj) - rigorous game tester
-* [phaze1G](https://github.com/phaze1G) - game designer / css support
+- The game is query-heavy by design (legacy architecture), so shared hosting can become a bottleneck quickly.
+- For medium/large servers, prefer dedicated or well-sized VPS infrastructure.

-**Thanks**
+## Installation (Web Installer)

-Many thanks to all those who recently played around with the project and tested it both, locally and on their 
-own servers. This includes [ZZJHONS](https://github.com/ZZJHONS), [DracoMilesX](https://github.com/DracoMilesX), 
-[phaze1G](https://github.com/phaze1G) , [martinambrus](https://github.com/martinambrus) and many others who were too shy to let us know that they use and enjoy 
-running this game :)
+1. Start services (Docker) or prepare your web+DB stack.
+2. Open `http://your-host/install`.
+3. Fill database settings:
+  - Host: `db` (Docker) or your DB host
+  - Port: usually `3306`
+  - DB/User/Password from your environment
+4. Complete installer steps:
+  - DB structure
+  - World data
+  - Croppers build
+5. After success, access the game root.

-Also, our thanks go to all both, the original and occasional developers, especially [yi12345](https://github.com/yi12345/), 
-[advocaite](https://github.com/advocaite/), [brainiacX](https://github.com/brainiacX/), [ronix](https://github.com/ronix/), 
-[MisterX](https://github.com/MisterX/), [Elio](https://github.com/eliopinho/) and many others who were part of this 
-project's history.
+## Environment Configuration

-Last but not least, our thanks go to [JetBrains](https://www.jetbrains.com/) for lending us a one-year full-featured 
-[open-source PHPStorm](https://www.jetbrains.com/buy/opensource/?product=phpstorm) (and other products) license! 
-Thanks guys, you're awesome :)
+Use `.env` (copy from `.env.example`) to manage deployment values.
+
+Main keys:
+
+- `MARIADB_ROOT_PASSWORD`
+- `MARIADB_DATABASE`
+- `MARIADB_USER`
+- `MARIADB_PASSWORD`
+- `DB_HOST`
+- `DB_PORT`
+
+Legacy compatibility keys (`MYSQL_*`) are still supported and can inherit MariaDB values.
+
+## Admin Panel
+
+Admin entrypoint:
+
+- `http://your-host/Admin/admin.php`
+
+Recent improvements include:
+
+- Users list under the `Users` menu
+- Better null/undefined handling in admin templates
+- Dynamic table prefix support in map tile queries
+
+## Performance Notes
+
+For large worlds (for example `400x400`), generation tasks can be expensive.
+
+Recent optimizations include:
+
+- world data generation tuning for bulk operations
+- croppers generation batching and progress streaming
+- safer DB/session handling during installer workflows
+
+For production-like loads, monitor:
+
+- DB CPU and slow queries
+- PHP-FPM/Apache worker limits
+- disk I/O during installer and reset operations
+
+## Troubleshooting
+
+Common checks:
+
+1. If installer cannot connect to DB:
+  - verify `DB_HOST`, port, user and password
+  - in Docker, host should be `db`, not `localhost`
+2. If permissions fail during install:
+  - ensure web user can write required runtime files/folders
+3. If pages show warnings after PHP upgrade:
+  - ensure latest code is deployed
+  - clear opcode/cache and retry
+
+For container-specific troubleshooting, see [DOCKER_README.md](DOCKER_README.md).
+
+## Development
+
+Useful commands:
+
+```bash
+# Start stack
+docker compose up -d
+
+# Logs
+docker compose logs -f web
+
+# Validate PHP files
+find . -name '*.php' -not -path './var/*' -print0 | xargs -0 -n1 php -l
+```
+
+Repository references:
+
+- Change history: [CHANGELOG.md](CHANGELOG.md)
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+
+## Community and Support
+
+- Issues: https://github.com/Shadowss/TravianZ/issues
+- Wiki: https://github.com/Shadowss/TravianZ/wiki
+- Chat: https://gitter.im/TravianZ-V8/Lobby
+
+## Credits
+
+Thanks to the original and current maintainers, contributors, testers, and the TravianZ community.
+
+Special acknowledgement to all legacy authors and maintainers who kept this project alive through multiple iterations.
+
+## License
+
+This project is licensed under the terms described in [LICENSE](LICENSE).