diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d0f92c --- /dev/null +++ b/README.md @@ -0,0 +1,327 @@ + +[![Stargazers][stars-shield]][stars-url] +[![Forks][forks-shield]][forks-url] +[![Issues][issues-shield]][issues-url] +[![MIT License][license-shield]][license-url] + + + +
+

AzerothCore Armory

+

+ A website to view your AzerothCore server's characters +
+ Report a Bug + · + Request a Feature + · + Ask a Question +

+
+ + + +
+ Table of Contents + +
    +
  1. + About + +
    2. +
  2. + Getting Started + +
    3. +
  3. + Usage + +
    4. +
  4. Features
    5. +
  5. Contributing
    6. +
  6. Show your Support
    7. +
  7. License
    8. +
  8. Contact
    9. +
+
+ + + +## About + +AzerothCore-Armory is a website that enables you to view your [AzerothCore][github-ac] server's characters and guilds. +At the time I started working on this project (end of 2021), there were virtually no modern and public/open-source armory projects. +I also noticed that such a tool was frequently requested in the AzerothCore Discord server, so I decided to make one. Hope you like it! + +
+ View screenshots + +![Main page](readme/img/index.png) +![Character page](readme/img/cayla.png) +![Character talents](readme/img/talents.png) +![Character achievements](readme/img/achievements.png) +![Guild page](readme/img/guild.png) +
+ + +### Built With + +* [Node.js](https://nodejs.org/) +* [TypeScript](https://www.typescriptlang.org/) +* [Express JS](https://expressjs.com/) +* [Handlebars](https://handlebarsjs.com/) +* [JQuery](https://jquery.com/) +* [DataTables](https://datatables.net/) +* [Bulma](https://bulma.io/) + +

(back to top)

+ + + +## Getting Started + +### Prerequisites + +* [Node.js](https://nodejs.org/en/download/) +* An [AzerothCore][github-ac]-based server database +* *(Optional)* [Docker](https://www.docker.com/get-started) + +### Installation + +1. Clone the repository: + * With HTTPS: + ```sh + git clone https://github.com/r-o-b-o-t-o/azerothcore-armory.git + ``` + **OR** + * With SSH: + ```sh + git clone git@github.com:r-o-b-o-t-o/azerothcore-armory.git + ``` +3. Install the dependencies: + ```sh + cd azerothcore-armory/ + npm install + ``` +4. Configure the application: copy `config.default.json` to `config.json` or `.env.example` to `.env` and edit the resulting file. + See the [Configuration Reference](#configuration-reference) below for a description of all values. +5. Download the model viewer's data: + * Download from script: + ```sh + npm run build + npm run fetchdata + ``` + **OR** + * Download the latest archive (`data.zip`) from the [Releases](https://github.com/r-o-b-o-t-o/azerothcore-armory/releases) page and extract it to the `data/` directory. + +### Configuration Reference + +
+ Main configuration + +| config.json | .env | Type | Default value | Description | +|--------------------------------|----------------------------------------------------|-------------------------------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `aowowUrl` | `ACORE_ARMORY_AOWOW_URL` | String | `"https://wotlkdb.com"` | The URL of the AoWoW database to use for tooltips and links | +| `websiteUrl` | `ACORE_ARMORY_WEBSITE_URL` | String | `"https://mywebsite.com"` | Your website's URL. Used to redirect to the homepage on error pages | +| `websiteName` | `ACORE_ARMORY_WEBSITE_NAME` | String | `"My Website"` | Your website's name. Displayed in the redirect button on error pages | +| `websiteRoot` | `ACORE_ARMORY_WEBSITE_ROOT` | String | `""` | The root of your armory's URL. If your armory is hosted on, for example, `http://mywebsite.com/azerothcore-armory`, the `websiteRoot` value should be `"/azerothcore-armory"` | +| `iframeMode` | `ACORE_ARMORY_IFRAME_MODE__`... | Object | | Settings for the iframe mode | +| `iframeMode.enabled` | `ACORE_ARMORY_IFRAME_MODE__ENABLED` | Boolean | `false` | Set to `true` if you want to embed the armory in an iframe | +| `iframeMode.url` | `ACORE_ARMORY_IFRAME_MODE__URL` | String | `"https://mywebsite.com/armory"` | Set this to the URL of the page that hosts the `iframe` | +| `loadDbcs` | `ACORE_ARMORY_LOAD_DBCS` | Boolean | `true` | Loads the DBC data from the `data` directory into memory when starting up. It is highly recommended to set this to `true`. Only use `false` to keep memory usage low, on a test server for example | +| `hideGameMasters` | `ACORE_ARMORY_HIDE_GAME_MASTERS` | Boolean | `true` | Hides Game Master characters if set to `true`. They will not be found in the search page, and their character pages will show a 404 error | +| `realms` | `ACORE_ARMORY_REALMS__`... | Array of objects | | An array of realm configurations | +| `realms[0].name` | `ACORE_ARMORY_REALMS__0__NAME` | String | `"AzerothCore"` | The name of the realm. Will be used in the URLs, shown on the character pages and in the search page if you have multiple realms | +| `realms[0].realmId` | `ACORE_ARMORY_REALMS__0__REALM_ID` | Number | `1` | The realm's ID, this must match the `id` column of the `realmlist` table in the auth database | +| `realms[0].authDatabase` | `ACORE_ARMORY_REALMS__0__AUTH_DATABASE` | String | `"acore_auth"` | The name of the auth database | +| `realms[0].charactersDatabase` | `ACORE_ARMORY_REALMS__0__CHARACTERS_DATABASE__`... | Database configuration object | | Configuration for the characters database. See "Database configuration" below | +| `worldDatabase` | `ACORE_ARMORY_WORLD_DATABASE__`... | Database configuration object | | Configuration for the world database. This is shared between all realms at the moment. See "Database configuration" below | +| `dbQueryTimeout` | `ACORE_ARMORY_DB_QUERY_TIMEOUT` | Number | `10000` | The maximum duration in milliseconds of a database query before it times out | +
+ +
+ Database configuration + +| config.json | .env | Type | Default value | Description | +|-------------|---------------|--------|---------------|------------------------------------------------| +| `host` | ...`HOST` | String | `"localhost"` | The hostname or IP address of the MySQL server | +| `port` | ...`PORT` | Number | `3306` | The port that the MySQL server runs on | +| `user` | ...`USER` | String | `acore` | The MySQL user used to connect to the database | +| `password` | ...`PASSWORD` | String | `acore` | The password for the specified MySQL user | +| `database` | ...`DATABASE` | String | | The name of the MySQL database | +
+ +

(back to top)

+ + + +## Usage + +Build the application: +```sh +npm run build +``` +Start the application: +```sh +npm start +``` +Open a web browser and navigate to http://localhost:48733 + +Other useful npm scripts: +* `npm run clean`: cleans the build directory +* `npm run watch`: watches for changes and rebuilds automatically, useful for development +* `npm run fetchdata`: downloads the data needed by the 3d model viewer +* `npm run cleardata`: clears the data downloaded for the 3d model viewer + +### With Docker + +You can also use [Docker](https://www.docker.com/), simply use `docker-compose`: +```sh +cd azerothcore-armory/ +docker-compose up -d +``` +*Note: the Docker version supports only the `.env` file for configuration, not `config.json`* + +### With an iframe + +You might want to integrate the application directly into your existing website using an `iframe`. +1. Set `iframeMode`.`enabled` to `true` in your configuration. +2. Set `iframeMode`.`url` in your configuration to the URL in your website that the armory will be accessible from (the page hosting the `iframe`). +3. Embed the code snippet below into your page. +Make sure you replace the URL `http://localhost:48733` with your Armory's URL (the same URL as `iframeMode`.`url`) at the end of the code snippet. +
+ Click to expand embed code + +```html + + + + + + +``` +
+ + +### Demo + +This repository is used in production over at [ChromieCraft](https://www.chromiecraft.com/armory), check it out there! + +

(back to top)

+ + + +## Features + +- [X] Characters list / search page +- [X] Character page + - [X] Online/offline status + - [X] Equipment with tooltips + - [X] 3d model, including mounts + - [X] Talent trees, including glyphs and dual spec support + - [X] Achievements + - [X] PvP statistics, including arena teams + - [ ] Statistics (from the achievements panel in-game) + - [ ] Reputations + - [ ] Stats (from the character sheet, i.e. health, mana, etc) +- [X] Guild page + - [X] Guild emblem + - [X] Members list + - [ ] PvE statistics +- [X] Multiple realms support +- [ ] PvE ladder +- [ ] PvP ladder + +See the [open issues](https://github.com/r-o-b-o-t-o/azerothcore-armory/issues) for a list of suggested features and known issues. + +

(back to top)

+ + + +## Contributing + +Any and all contributions are **greatly appreciated**. + +If you have a suggestion that would make this project better, feel free to fork the repository and create a Pull Request. You can also open a [Feature Request][feature-request]. + +

(back to top)

+ + + +## Show your Support + +⭐️ Give the project a star if you like it! + +Buy Me a Coffee at ko-fi.com + +

(back to top)

+ + + +## License + +Distributed under the MIT License. See the [`LICENSE`][license-url] file for more information. + +

(back to top)

+ + + +## Contact + + Feel free to get in touch with me on Discord: `Roboto#9185` + +

(back to top)

+ + + + +[github-ac]: https://github.com/azerothcore/azerothcore-wotlk +[stars-shield]: https://img.shields.io/github/stars/r-o-b-o-t-o/azerothcore-armory.svg?style=flat +[stars-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/stargazers +[forks-shield]: https://img.shields.io/github/forks/r-o-b-o-t-o/azerothcore-armory.svg?style=flat +[forks-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/network/members +[issues-shield]: https://img.shields.io/github/issues/r-o-b-o-t-o/azerothcore-armory.svg?style=flat +[issues-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/issues +[license-shield]: https://img.shields.io/github/license/r-o-b-o-t-o/azerothcore-armory.svg?style=flat +[license-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/blob/master/LICENSE +[feature-request]: https://github.com/r-o-b-o-t-o/azerothcore-armory/issues/new?template=feature_request.yml diff --git a/readme/img/achievements.png b/readme/img/achievements.png new file mode 100644 index 0000000..68da175 Binary files /dev/null and b/readme/img/achievements.png differ diff --git a/readme/img/cayla.png b/readme/img/cayla.png new file mode 100644 index 0000000..35ad1b0 Binary files /dev/null and b/readme/img/cayla.png differ diff --git a/readme/img/guild.png b/readme/img/guild.png new file mode 100644 index 0000000..b8197f1 Binary files /dev/null and b/readme/img/guild.png differ diff --git a/readme/img/index.png b/readme/img/index.png new file mode 100644 index 0000000..963fa9f Binary files /dev/null and b/readme/img/index.png differ diff --git a/readme/img/talents.png b/readme/img/talents.png new file mode 100644 index 0000000..2fe4d4c Binary files /dev/null and b/readme/img/talents.png differ