Skip to content

Commit 86a470b

Browse files
r-o-b-o-t-or-o-b-o-t-o
committed
docs: add readme
1 parent 7315de7 commit 86a470b

File tree

6 files changed

+327
-0
lines changed

6 files changed

+327
-0
lines changed

‎README.md

+327
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
<!-- SHIELDS -->
2+
[![Stargazers][stars-shield]][stars-url]
3+
[![Forks][forks-shield]][forks-url]
4+
[![Issues][issues-shield]][issues-url]
5+
[![MIT License][license-shield]][license-url]
6+
7+
8+
<!-- SUMMARY -->
9+
<div align="center">
10+
<h1 align="center">AzerothCore Armory</h1>
11+
<p align="center">
12+
A website to view your <a href="https://github.com/azerothcore/azerothcore-wotlk">AzerothCore</a> server's characters
13+
<br />
14+
<a href="https://github.com/r-o-b-o-t-o/azerothcore-armory/issues/new?template=bug_report.yml">Report a Bug</a>
15+
·
16+
<a href="https://github.com/r-o-b-o-t-o/azerothcore-armory/issues/new?template=feature_request.yml">Request a Feature</a>
17+
·
18+
<a href="https://github.com/r-o-b-o-t-o/azerothcore-armory/issues/new?template=question.yml">Ask a Question</a>
19+
</p>
20+
</div>
21+
22+
23+
<!-- TABLE OF CONTENTS -->
24+
<details>
25+
<summary>Table of Contents</summary>
26+
27+
<ol>
28+
<li>
29+
<a href="#about">About</a>
30+
<ul>
31+
<li><a href="#built-with">Built With</a></li>
32+
</ul>
33+
</li>
34+
<li>
35+
<a href="#getting-started">Getting Started</a>
36+
<ul>
37+
<li><a href="#prerequisites">Prerequisites</a></li>
38+
<li><a href="#installation">Installation</a></li>
39+
<li><a href="#configuration-reference">Configuration Reference</a></li>
40+
</ul>
41+
</li>
42+
<li>
43+
<a href="#usage">Usage</a>
44+
<ul>
45+
<li><a href="#with-docker">With Docker</a></li>
46+
<li><a href="#with-an-iframe">With an iframe</a></li>
47+
<li><a href="#demo">Demo</a></li>
48+
</ul>
49+
</li>
50+
<li><a href="#features">Features</a></li>
51+
<li><a href="#contributing">Contributing</a></li>
52+
<li><a href="#show-your-support">Show your Support</a></li>
53+
<li><a href="#license">License</a></li>
54+
<li><a href="#contact">Contact</a></li>
55+
</ol>
56+
</details>
57+
58+
59+
<!-- ABOUT -->
60+
## About
61+
62+
AzerothCore-Armory is a website that enables you to view your [AzerothCore][github-ac] server's characters and guilds.
63+
At the time I started working on this project (end of 2021), there were virtually no modern and public/open-source armory projects.
64+
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!
65+
66+
<details>
67+
<summary>View screenshots</summary>
68+
69+
![Main page](readme/img/index.png)
70+
![Character page](readme/img/cayla.png)
71+
![Character talents](readme/img/talents.png)
72+
![Character achievements](readme/img/achievements.png)
73+
![Guild page](readme/img/guild.png)
74+
</details>
75+
76+
77+
### Built With
78+
79+
* [Node.js](https://nodejs.org/)
80+
* [TypeScript](https://www.typescriptlang.org/)
81+
* [Express JS](https://expressjs.com/)
82+
* [Handlebars](https://handlebarsjs.com/)
83+
* [JQuery](https://jquery.com/)
84+
* [DataTables](https://datatables.net/)
85+
* [Bulma](https://bulma.io/)
86+
87+
<p align="right">(<a href="#top">back to top</a>)</p>
88+
89+
90+
<!-- GETTING STARTED -->
91+
## Getting Started
92+
93+
### Prerequisites
94+
95+
* [Node.js](https://nodejs.org/en/download/)
96+
* An [AzerothCore][github-ac]-based server database
97+
* *(Optional)* [Docker](https://www.docker.com/get-started)
98+
99+
### Installation
100+
101+
1. Clone the repository:
102+
* With HTTPS:
103+
```sh
104+
git clone https://github.com/r-o-b-o-t-o/azerothcore-armory.git
105+
```
106+
**OR**
107+
* With SSH:
108+
```sh
109+
git clone [email protected]:r-o-b-o-t-o/azerothcore-armory.git
110+
```
111+
3. Install the dependencies:
112+
```sh
113+
cd azerothcore-armory/
114+
npm install
115+
```
116+
4. Configure the application: copy `config.default.json` to `config.json` or `.env.example` to `.env` and edit the resulting file.
117+
See the [Configuration Reference](#configuration-reference) below for a description of all values.
118+
5. Download the model viewer's data:
119+
* Download from script:
120+
```sh
121+
npm run build
122+
npm run fetchdata
123+
```
124+
**OR**
125+
* 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.
126+
127+
### Configuration Reference
128+
129+
<details>
130+
<summary>Main configuration</summary>
131+
132+
| config.json | .env | Type | Default value | Description |
133+
|--------------------------------|----------------------------------------------------|-------------------------------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
134+
| `aowowUrl` | `ACORE_ARMORY_AOWOW_URL` | String | `"https://wotlkdb.com"` | The URL of the AoWoW database to use for tooltips and links |
135+
| `websiteUrl` | `ACORE_ARMORY_WEBSITE_URL` | String | `"https://mywebsite.com"` | Your website's URL. Used to redirect to the homepage on error pages |
136+
| `websiteName` | `ACORE_ARMORY_WEBSITE_NAME` | String | `"My Website"` | Your website's name. Displayed in the redirect button on error pages |
137+
| `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"` |
138+
| `iframeMode` | `ACORE_ARMORY_IFRAME_MODE__`... | Object | | Settings for the iframe mode |
139+
| `iframeMode.enabled` | `ACORE_ARMORY_IFRAME_MODE__ENABLED` | Boolean | `false` | Set to `true` if you want to embed the armory in an iframe |
140+
| `iframeMode.url` | `ACORE_ARMORY_IFRAME_MODE__URL` | String | `"https://mywebsite.com/armory"` | Set this to the URL of the page that hosts the `iframe` |
141+
| `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 |
142+
| `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 |
143+
| `realms` | `ACORE_ARMORY_REALMS__`... | Array of objects | | An array of realm configurations |
144+
| `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 |
145+
| `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 |
146+
| `realms[0].authDatabase` | `ACORE_ARMORY_REALMS__0__AUTH_DATABASE` | String | `"acore_auth"` | The name of the auth database |
147+
| `realms[0].charactersDatabase` | `ACORE_ARMORY_REALMS__0__CHARACTERS_DATABASE__`... | Database configuration object | | Configuration for the characters database. See "Database configuration" below |
148+
| `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 |
149+
| `dbQueryTimeout` | `ACORE_ARMORY_DB_QUERY_TIMEOUT` | Number | `10000` | The maximum duration in milliseconds of a database query before it times out |
150+
</details>
151+
152+
<details>
153+
<summary>Database configuration</summary>
154+
155+
| config.json | .env | Type | Default value | Description |
156+
|-------------|---------------|--------|---------------|------------------------------------------------|
157+
| `host` | ...`HOST` | String | `"localhost"` | The hostname or IP address of the MySQL server |
158+
| `port` | ...`PORT` | Number | `3306` | The port that the MySQL server runs on |
159+
| `user` | ...`USER` | String | `acore` | The MySQL user used to connect to the database |
160+
| `password` | ...`PASSWORD` | String | `acore` | The password for the specified MySQL user |
161+
| `database` | ...`DATABASE` | String | | The name of the MySQL database |
162+
</details>
163+
164+
<p align="right">(<a href="#top">back to top</a>)</p>
165+
166+
167+
<!-- USAGE -->
168+
## Usage
169+
170+
Build the application:
171+
```sh
172+
npm run build
173+
```
174+
Start the application:
175+
```sh
176+
npm start
177+
```
178+
Open a web browser and navigate to http://localhost:48733
179+
180+
Other useful npm scripts:
181+
* `npm run clean`: cleans the build directory
182+
* `npm run watch`: watches for changes and rebuilds automatically, useful for development
183+
* `npm run fetchdata`: downloads the data needed by the 3d model viewer
184+
* `npm run cleardata`: clears the data downloaded for the 3d model viewer
185+
186+
### With Docker
187+
188+
You can also use [Docker](https://www.docker.com/), simply use `docker-compose`:
189+
```sh
190+
cd azerothcore-armory/
191+
docker-compose up -d
192+
```
193+
*Note: the Docker version supports only the `.env` file for configuration, not `config.json`*
194+
195+
### With an iframe
196+
197+
You might want to integrate the application directly into your existing website using an `iframe`.
198+
1. Set `iframeMode`.`enabled` to `true` in your configuration.
199+
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`).
200+
3. Embed the code snippet below into your page.
201+
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.
202+
<details>
203+
<summary>Click to expand embed code</summary>
204+
205+
```html
206+
<style>
207+
#armory-iframe {
208+
/*
209+
* Using min-width to set the width of the iFrame, works around an issue in iOS that can prevent the iFrame from sizing correctly.
210+
* See: https://github.com/davidjbradshaw/iframe-resizer
211+
*/
212+
width: 1px;
213+
min-width: 100%;
214+
215+
border: none;
216+
}
217+
</style>
218+
219+
<iframe id="armory-iframe"></iframe>
220+
221+
<script type="application/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/js/iframeResizer.min.js"></script>
222+
<script type="application/javascript">
223+
let resizeSetup = false;
224+
window.addEventListener("message", (ev) => {
225+
if (ev.data.url !== undefined) {
226+
const url = ev.data.url.trim().replace(/^\//, "");
227+
window.history.replaceState(null, null, url === "" ? window.location.pathname : ("?" + url));
228+
} else if (ev.data === "contentLoaded") {
229+
if (!resizeSetup) {
230+
iFrameResize({ checkOrigin: false, autoResize: true }, "#armory-iframe");
231+
resizeSetup = true;
232+
} else {
233+
document.getElementById("armory-iframe").iFrameResizer.resize();
234+
}
235+
}
236+
});
237+
238+
const iframe = document.getElementById("armory-iframe");
239+
const url = window.location.search.replace(/^\?/, "");
240+
iframe.src = "http://localhost:48733/" + url;
241+
</script>
242+
```
243+
</details>
244+
245+
246+
### Demo
247+
248+
This repository is used in production over at [ChromieCraft](https://www.chromiecraft.com/armory), check it out there!
249+
250+
<p align="right">(<a href="#top">back to top</a>)</p>
251+
252+
253+
<!-- FEATURES -->
254+
## Features
255+
256+
- [X] Characters list / search page
257+
- [X] Character page
258+
- [X] Online/offline status
259+
- [X] Equipment with tooltips
260+
- [X] 3d model, including mounts
261+
- [X] Talent trees, including glyphs and dual spec support
262+
- [X] Achievements
263+
- [X] PvP statistics, including arena teams
264+
- [ ] Statistics (from the achievements panel in-game)
265+
- [ ] Reputations
266+
- [ ] Stats (from the character sheet, i.e. health, mana, etc)
267+
- [X] Guild page
268+
- [X] Guild emblem
269+
- [X] Members list
270+
- [ ] PvE statistics
271+
- [X] Multiple realms support
272+
- [ ] PvE ladder
273+
- [ ] PvP ladder
274+
275+
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.
276+
277+
<p align="right">(<a href="#top">back to top</a>)</p>
278+
279+
280+
<!-- CONTRIBUTING -->
281+
## Contributing
282+
283+
Any and all contributions are **greatly appreciated**.
284+
285+
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].
286+
287+
<p align="right">(<a href="#top">back to top</a>)</p>
288+
289+
290+
<!-- SUPPORT -->
291+
## Show your Support
292+
293+
⭐️ Give the project a star if you like it!
294+
295+
<a href="https://ko-fi.com/roboto" target="_blank"><img height="35" style="border:0px; height:46px;" src="https://cdn.ko-fi.com/cdn/kofi5.png?v=3" border="0" alt="Buy Me a Coffee at ko-fi.com" />
296+
297+
<p align="right">(<a href="#top">back to top</a>)</p>
298+
299+
300+
<!-- LICENSE -->
301+
## License
302+
303+
Distributed under the MIT License. See the [`LICENSE`][license-url] file for more information.
304+
305+
<p align="right">(<a href="#top">back to top</a>)</p>
306+
307+
308+
<!-- CONTACT -->
309+
## Contact
310+
311+
<img src="https://img.shields.io/badge/Discord-5865F2?style=flat&logo=discord&logoColor=white"/> Feel free to get in touch with me on Discord: `Roboto#9185`
312+
313+
<p align="right">(<a href="#top">back to top</a>)</p>
314+
315+
316+
<!-- MARKDOWN LINKS -->
317+
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
318+
[github-ac]: https://github.com/azerothcore/azerothcore-wotlk
319+
[stars-shield]: https://img.shields.io/github/stars/r-o-b-o-t-o/azerothcore-armory.svg?style=flat
320+
[stars-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/stargazers
321+
[forks-shield]: https://img.shields.io/github/forks/r-o-b-o-t-o/azerothcore-armory.svg?style=flat
322+
[forks-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/network/members
323+
[issues-shield]: https://img.shields.io/github/issues/r-o-b-o-t-o/azerothcore-armory.svg?style=flat
324+
[issues-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/issues
325+
[license-shield]: https://img.shields.io/github/license/r-o-b-o-t-o/azerothcore-armory.svg?style=flat
326+
[license-url]: https://github.com/r-o-b-o-t-o/azerothcore-armory/blob/master/LICENSE
327+
[feature-request]: https://github.com/r-o-b-o-t-o/azerothcore-armory/issues/new?template=feature_request.yml

‎readme/img/achievements.png

172 KB
Loading

‎readme/img/cayla.png

429 KB
Loading

‎readme/img/guild.png

77.3 KB
Loading

‎readme/img/index.png

112 KB
Loading

‎readme/img/talents.png

321 KB
Loading

0 commit comments

Comments
 (0)