# CatCaster Team 07

## Opdeling features
### Eerste versie (vb. enkel kat op scherm laten bewegen):
* WebRTC (Jordy & Olivier): verkregen sensordata sturen tussen van controller naar het scherm met zijn kat
* Controller: Tilten om kat links/rechts, boven/onder te bewegen, schudden om te springen.
* REST (Thijs & Warre): Server maken waarop spel runt en data van connecties bijhouden op server
* Client side pages (Mihail & Turan): sensordata meten en client side katten op schijven -> Planeet is een cirkle. Er worden katten getekend en ze kunnen bewegen. Portals werken op een scherm.
* Scherm Setup (Jef & Jacob):
* QR met genereren met URL op basis van screen ID
* Foto trekken met gsm op controller client
* Locaties van meerdere beeldschermen + identificatie met QR codes via foto
### Verdere uitbreiding
* (extra) bepaling posities o.b.v. qr-codes

### Bullets voor minimale implementatie
- [x] [CS1] Clients load the game in a web browser.
- [x] [CS2] The URL for a screen ends in /screen/.
- [x] [CS3] (The URL for a controller ends in /controller/. (You probably do not need this.))
- [x] [CS4] Each client gets an id generated by the server.
- [x] [CS5] The id is a hexadecimal string (like the hashes from git) and the server guarantees that the first 8 characters (alternatively 4) can be used as a short and unique version of the id.
- [x] [CS6] As soon as a client knows its id it will reload the page and add the id as a GET parameter. (The technical team thought this would help if anything goes astray, then the user can just reload the page and at least we have retained our id. They think that things can get implemented in such a way that connections are automatically restored and there is minimal disruption in the game.)
- [x] [CS7] If the GET parameter is already present then the server does not generate a new id.
- [x] [CS8] Each client establishes a websocket connection to the server.
- [x] [CS9] The client sends its id over the websocket connection by a message { id: "..." } as a kind of “helo” (note that this is not a typo, this spelling is actually used in the SMTP protocol).
- [x] [CS10] The server closes connections for unknown id’s.
- [x] [CS11] We are currently not protecting against hijacking of id’s.

- [x] [S1] A screen can be in two states: free or game.
- [x] [S2] When a screen is in free mode it displays a QR code which contains the URL of the server with /screen/{short-id} at the end, where the {short-id} is the 8 (or 4) character short id for this screen. (Note that you could type in this URL manually and it should also work…)
- [x] [S3] When a screen is in free mode and a controller scanning this QR code goes to that URL (by using the builtin functionality of the smartphone), then a menu will be presented on the smartphone:

Play on single screen
Detect multi-screen
… (other possible options)

[S4] The option “Play on single screen” will let the controller play the CatCaster game on the single screen.
[S6] When the screen is in game mode then scanning the QR code will let another controller join the game.
[S8] In game mode the QR code is placed somewhere out of the way such that the game can take up most of the “screen” size.
[S9] Note that a screen will be instructed by the server to change mode (through the websocket connection): { mode: "free" | "CatCaster" }. (Note that we say “CatCaster” instead of “game”…)

[I1] A screen will have a designated area where technical information is shown.
[I2] It shows the short id of the screen.
[I3] It shows the state the screen is in (“free” or “CatCaster” (game)).
[I4] It shows the connection status with the server (websocket). (Also show when the screen is trying to reconnect…)
[I6] It shows the connection status with all connected controllers (WebRTC data) to this screen. The controllers are identified by their short id.

[CC1] When a controller selects “Play on single screen” or “Play on multi-screen” the CatCaster game starts on all the screens involved.
[CC2] When a controller scans a QR code of a screen in game mode it will join the running game (this could be a multi-screen game).
[CC3] When a controller joins a game it establishes WebRTC data channels to the screens involved. We use the websocket to the server as our signaling channel to set up the WebRTC connection.
[CC4] The cat is spawned at a random planet (of a random screen in multi-screen mode), similar to when a cat died and is re-spawned (see further).
[CC5] The id of the controller should be visible somewhere on or above the cat.
[CC6] Cats should be distinguishable, e.g., by different colors.
[CC7] When a screen starts the CatCaster game it generates between one and three planets. (To make it interesting a single screen game should probably generate three planets.)
[CC8] A planet is a disk of which the center is fixed but the distribution of weight/cats will make the disk tilt in that direction.
[CC9] Cats which do not try to move in a certain direction will slide.
[CC10] Cats which slide off a disk die and re-spawn on a random planet. (The player should be able to recognize its cat. To give the player more time this could be animated, and during this re-spawning period the cat cannot slide off its new planet.)
[CC11] The planets/disks can be very simply represented by an oval.
[CC12] The portals are situated where the straight lines from the center of the different disks connect to their neighbors (Voronoi).
[CC13] Portals can be simply marked by marking an arc on the disk.
[CC14] If a cat is close enough to a portal (on the edge of the disk) then shaking the controller in the direction of the other planet will cast the cat from one planet to the other. (The shaking does not necessarily need to be in the right direction.)
[CC15] There is a lot of choice in tuning parameters, these should all be in a separate configuration file (or at least in a designated place).
[CC16] A controller sends the orientation data directly to the screen where its cat is on using the WebRTC connection to the particular screen.
[CC17] A screen determines the positions of all the cats on that screen.
[CC19] The WebRTC connection between the controller and the screens can be set into a UDP kind of mode by specifying dataChannelOptions = { ordered: false, maxRetransmit: 0 }.
[CC22] For debugging mode the CatCaster game should be playable on a single screen using the keyboard attached to the computer. This mode could e.g. by activated by pressing x after which a cat is spawned which can be controlled by the arrow keys and space bar.
[CC23] Construct a formula to take into account the weight of the cats and how your planet tilts. (Think of easy unit tests.)
[CC24] Construct a formula on how the sensor data from a controller is used to move a cat on a tilted planet. (Think of easy unit tests.)
[CC25] Construct a formula to detect if a cat is close enough to a portal.

#### Werkt al 17-3-2022 week 5
* Meerdere schermen met meerdere controllers verbinden met elkaar
* Minimale versie spel spelen met 1 scherm en 1 controller
* Client-server requirements [CS 1-10]
* Qr-codes scanner van multiple screens + voronoi-diagram van de relatieve posities
* Technical information on screen [I1-2,I4-6], [C1]
* [CC3, CC11, CC12, CC14, CC16, CC22-25]

#### week 5, 17-3-2022 planning: best klaar voor paasvakantie
* Qr-code feature mergen met server/webRTC delen[D]
* Meerdere katten (controllers), meerdere planeten op 1 scherm
* Verschillende states van een scherm [S]

#### week 5, 17-3-2022 planning: na paasvakantie
* Kat sliden, planeten bewegen/kantelen [CC]
* Binnen 10 minuten kunnen reconnecten [CS11]
* Multiple screens

# Guide voor het runnen van de applicatie
## Stap 1
Zorg ervoor dat je computer en controller op dezelfde internetverbinding zitten (bv. hotspot). Niet KULeuven internet!!!
## Stap 2
In WSL of terminal, ga naar de map team-07-catcaster en run daar volgende command:

npm run start-server

## Stap 3
### Voor Windows:
In cmd:

ipconfig

Onder de tab 'Wireless LAN adapter Wi-Fi', zoek naar 'IPv4 Address' en op deze lijn staat je IP address
### Voor Mac:
Volgende runnen in terminal voor IP-address:

ipconfig getifaddr en0

## Stap 4
Ga naar volgende website: ***`https://<ip_address>:8000/catcaster/screen/`***
## Stap 5
Op je gsm ga je naar je QR-scanner app en scan je de QR-code op het scherm. (Meerdere gsm's kunnen deze code scannen op voorwaarde dat zij ook op dezelfde Wi-Fi verbinding zitten.)
## Stap 6
Tik op je gsm scherm om te beginnen met spelen.

## Als volgende niet werkt
### Na stap 3
#### 1
Zorg dat node geinstalleerd is en in path staat:
[https://nodejs.org/en/download/](https://nodejs.org/en/download/)
#### 2
In cmd of terminal (dus niet WSL!!!!):
1. Ga naar git map: `'team-07-catcaster'`
2. Run: `node dist/server/index.js`
#### 3
Volg terug de overige stappen in de juiste volgorde.

# Multiple screen aanpak
## absolute coördinaten (spelcoördinaten) berekenen uit foto
* KLAAR: `window.innerheight` en alle planeten doorsturen via WebSocket
* absolute coördinaten van middelpunten van schermen berekenen door de foto met qr-codes
* echte window.innerheight waardes vergelijken met pixels op foto (hoekpunten van qr-code) (verhouding berekenen PER SCHERM!)
* absolute coördinaten van middelpunten van schermen herleiden dmv vorige verhouding
* absolute coordinaten berekenen van planeten (relatieve coördinaten planeten + absolute coördinaten middelpunt schermen)
* triangularisatie van alle planeten van alle schermen
* portalen toevoegen aan planeten dmv de uitkomst van de triangularisatie
* portalen terug doorsturen naar schermen (moet dit of passen ze automatisch aan???)

# Nog te doen (5/05):
* Errorcatch voor de qr scan -> CHECK
* Bij teleporteren effe stilstaan -> CHECK
* Controller toont kleur kat en op welk scherm hij moet zijn -> CHECK
* Linter (ook voor HTML pages en voor javascript binnen HTML pages) -> CHECK
* Na 10 minuten connection closed/lost wordt de connectie gedisconnect en wordt dit getoond op het scherm -> CHECK
* Nieuwe controller die de qr code niet scant krijgt niet direct menu join game/end game -> CHECK
* Eindigen game -> schermen terug in free state en tonen QR code en state 'game' = 'CatCaster' -> CHECK
* Respawnen op random planeet bij doodgaan ipv dezelfde -> CHECKd
* Niet altijd 3 planeten op elke scherm -> CHECK

# Nog te doen (14/05):
* ID bij katten -> Werkt, maar ID's draaien niet mee
* Lijnen tussen de portalen van aanburende planeten -> BEZIG
* Kat deleten nadat controller disconnect (WebRTC) -> BEZIG