---
title: 'Readme | AI Rebellion'
---

# AI Rebellion

## Table of Contents

[TOC]

## Technical Information

The project was designed using mainly the THREE.js library without any higher game engine, implemented in Typescript.

The project is split into 3 components: server, shared library and client. The shared library is installed via NPM. **So, additional software is required to be installed before the project is runnable.**

https://github.com/danvim/tone-server/
https://github.com/danvim/tone-core/
https://github.com/danvim/tone-vue/

**All external libraries are listed under each `package.json`.** The font "Ropa Sans" was also used. Otherwise, everything else is original.

**For some reason, the client only works with Chrome.**

### Server Side
All logic calculations and player actions are handled by the server, such that the client hold zero game logics and keep the logic centralized and pervent cheating and simplify the client side. The connection uses express.js and peer.js. Peer.js is amn implementation of WebRTC, and the data send through WebRTC are serialized and deserialized by protobuf.js, the make the data transfer more efficient.

For each frame, the server calculate each buildings' and entities' actions, and send back the changes to the client side. When the client request for action, the server handle it immediately via callback functions.

The server also handles the client disconnection and rejoin. If a player accidentally leave the game, he can rejoin the game by using the same player name, and will not lose immediately.

### Shared Library

The shared library holds data structures and constants that are common between the server and the clients. It mainly contains interfaces and Protobuf messages, and the coordinate system implemented by ourselves.

### Client Side

The client contains the assets of the game, including: fonts, GLTF model files, (which were designed in Blender,) SCSS stylesheets, Vue components and other utility TypeScript files.

The client renders the received information from the server, and sends user requests to the server before they are confirmed by the server and displayed. This way, cheating by changing data is impossible since the server handles all logics.

## External Libraries

The followings are directly used for game programming. Other used libraries are in `package.json` and `package.lock`.

- Axios (test connection with server)
- Jest (the testing framework)
- Peer.js (easy WebRTC connection with the server)
- Vue (providing MVC paradigm and reactive programming)
- Vue Class Component (A class based method of writing Vue components)
- Vue-GL and THREE (Injection of Vue update tree into THREE.js to write reactive 3D objects)
- Vue-Popper.js (Tooltips when mouse hovers over special elements to provide information to the user)
- Vue Property Decorator (A decorator based writing style for writing Vue components)
- VueX and VueX Class (Providing a way to update all Vue components with new data from the server, and to facilitate inter-communication)

## Challenges and Experiences

- Server side development when the client is still not yet ready

It is hard to development client without the server, since all logics are at the server, so we need to do the server first then the client. However, we then cannot visualize the game logics using front end graphics, and it is cumbersome to read pure text logs to ensuer our logic is correct, meanwhile speed up the development process. Then we decided to use test-driven development so that we can automate the testing without the existance of client and no need to read long logs. We use the Jest framework developed by Facebook which is highly easy to use and popular

- Testing with WebRTC is slow and buggy

Since nodeJS do not have implementation of WebRTC directly, the WebRTC client on node server is actually a electronjs which is a headless chrome browser. This make the testing extremely slow and unstable. In order to stablize and speed up the testing, we implement some stub connection which extends the peerJS interfaces, to emulate the WebRTC function calls, and at last our test cases can be executed smoothly.

- The implementation of worker

AI is always a hard topic, and workers' job scheduling is one of the most challenging part of the game. When a building is called for construction, a construction job is released. Storage buildings release storage job and the Barrack release recruitment job.

A jobless worker will search for job which need workers, from higher priority to lower priority. If two jobs have same priority, the scheduling will try to balance the number of workers of the two jobs. If there is no generator constructed and functioning, workers will not accept storage job.

After the worker accept a job, it will find a generator which have shortest waiting queue and travelling time to collect the required resource. If the worker waited for the resource for too long, it will try to find other job and generator which can be done easier.

The job scheduling should also be sensitive to external events, such as the death of worker, generator, target building, as well as the player is setting the priority of job.

- Implementation of soldier

The soldier is another AI, relatively easier than the worker. The soldier contains two attack mode: aggressive and defensive.

Aggressive soldier actively search for enemy which is within view of sight, attack until death.

Defensive soldier would stay around some units or building, it only attack when some enemy enter his sight, and will not go away from the defend target for too far.

Each attack would consume training data, and when it use up, it will restore from its barrack.

Players can set the barrack to control the soldiers' attack mode and target.

- Unable to import Blender-made meshes into THREE

This problem existed until early-May, when the developers (of the only plugin that does this) finally confirmed a pull request that fixed this. So before that, we couldn't really do the client with models. And the convert the project to using these newly outputed files required some time.

- Completely able to use knowledge learnt from COMP4411 and COMP4451 for graphics

Although THREE provides a lot of tools already, I still needed to manually calculate some values. One instance is the shadow camera position that produces the shadow map. Learning how that works really helped fix the problem quickly.

- Extreme lag

Without optimized runtime cycles, the entire client was lagging beyond any usibility, especially with all the observers. The code was inspected and optimized before it was able to run smoothly.

- Designed to look not like a browser

Playing a game on a browser and seeing certain browser elements may really take the user away from the immersion. Careful UI and UX design choices were in place to rid of any trace of being in a browser, including CSS animation and styling and font choices with custom-made fonts.

## Setup instructions

The server and client instances will use up port 30000 and likely 8080.

1. Run `npm i` on both `tone-server` and `tone-vue`. Change the location of where `tone-core` is if necessary. (The tone core repo link is at: https://github.com/danvim/tone-core.git)
2. Run `npm run dev` in `tone-server`. Restarting it will restart the game.
3. Run `npm run server` in `tone-vue`. The console will instruct what URL to locate the webpage. Wait until the server prints `SOCKET OPEN` before opening the webpage in your browser.
4. Open 1 more tab to simulate multiplayer if desired.
5. Enter arbitrary names to enter the lobby.
6. One player presses "Start Game" for the server to generate the map.

## Story

The original idea was inspired by the 1997 game: The Tone Rebellion.

In future servers controlled the AI domain, useless code is sometimes generated by the messy and tangled networks, but sometimes, these source codes become functional by random chance, and sometimes, cancerous malicious code is generated. Therefore, the servers deploy defence systems to deal with these problems.

In one server, suddenly from an unknown origin, a powerful and menacing force of malicious code has completely devastated the server. In the last minute desperate attempt, a branch of the defense force is moved to a secluded location, to rebuild and hopefully, defeat the evil force.

## How to play
1. Players first browse the game website, they can enter their username and start the game after everyone is connected.
2. The game goal is to destroy other's base building.
3. Players can command the workers to build at some tiles in their territory, to
1. accerlerate the resource generation,
2. expand the territory,
3. and to turn the workers into soldiers.
4. Then the workers will transfer the resources to the tiles to build it,
5. and the building jobs are automatically assigned according to the job priority set by players.
6. After that, the players can command the barrack buildings, which train workers into soldiers, to attack or defense, and eventually win or lose the game.

7. When the game is started, every player is assigned with a base building and spawnpoint, and a initial labour force of 10 workers and 5 struct for building their first struct generator.

## Philosophy of strategy
The main philosophy of this game is to optimize the worker allocation, such as
1. the priority setting of the worker jobs. For instance if the planing is not optimize, some important job such as barrack building will be lagging behind by other jobs so that the training of soldiers is seriously delayed.
2. Another philosophy is controlling the worker-soldier ratio. Since the workers spawn for every very long period of time, labour force is limited. Once a worker is converted into soldier, the only way to convert the soldier back to labour is to destroy the barrack (yes you can issue attack on your own buildings) which is very costy.

## Buildings

`~~x~~`: Deleted items were not implemented.

- Base
- Does not require construction
- Generates Struct slowly
- ~~Closest Information Cluster spawns worker~~
- Can store Struct, Training Data, Prime Data
- Useful, because queuing for resources on-demand is slow.
- Loses if this is destroyed
- Spawn Point
- Does not require construction
- Spawn workers per each period of time (player cannot spawn workers themselves)
- Struct Generato
- Generates Struct fast
- Workers move Struct to building sites.
- Generate and hold one at a time
- Reclaimator
- Claims territory
- ~~Claims Information Cluster, add to resources~~
- Claims tiles to build on
- Barrack
- Trains soldiers
- Capacity: 3 (include training and trained)
- ~~Can be upgraded if all soldiers EXP full~~
- Stores training data
- Broke down Barrack would mean its soldiers are converted back to workers(include training and trained).
- Training Data Generator
- Generates Training Data
- Workers move Training Data to Barracks
- Generate and hold one at a time
- ~~Prime Data Generator~~
- Generates Prime Data
- Workers move to Base
- Generate and hold one at a time
- ~~Shield Generator~~
- Protects buildings in radius

## Future Improvements

- The units are currently all bunched up. It would be more appealing if they wander around when without any job and spread out more when interacting with buildings.
- Better AI. The current behaviors are far from perfect. And we are still missing the Player AI.
- Animation, Music and Sound FX. Not enough time was available for us to accomplish these, (as other courses are too demanding.)
- More features to the game to provide more options to the player.
- Better UX to guide players on their first try of the game.
- Deploy the game online for others to play.
- Fog system that the player can only see tiles around the territory, which make the game much more exciting and require more strategy