diff --git a/src/content/docs/Splashkit/Applications/ApplicationsEpic-T12022.md b/src/content/docs/Splashkit/Applications/ApplicationsEpic-T12022.md new file mode 100644 index 00000000..16ddf592 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/ApplicationsEpic-T12022.md @@ -0,0 +1,69 @@ +# SplashKit (Applications) + +## Background/Context + +SplashKit is widely used to create 2D games. It is proposed to extend this for games to be set up +and added to a physical arcade machine where they can be played and showcased. + +## Business value + +Games are an attraction to different age groups, this functionality of providing games and an +article including content to help create similar games would be helpful for interested individuals. + +## What needs to happen + +Creating a method to upload games and store them locally on a system, have them be selected and +played at the user’s leisure. Validation checks on all uploaded games before being playable +(manually, at least initially) for malice/inappropriate content. Create a cool game demonstrating +all functionality of SplashKit. A step-by-step article guide of How to create a Cool game. Guide +should be uploaded to the SplashKit.io website. Document design decisions, process and +how-to-guides. + +## In-Scope + +The first game of Arcade machine. Article guide. + +## Out-Scope + +Building the hardware (presently; may be in scope for future trimesters) + +## Assumptions/Dependencies + +First game needs to be ready, in order to add it to the arcade/showcase. Raspberry Pi will merge +with preconfigured controls without too much complication + +## UI/UX considerations + +- Arcade layout +- Arcade gallery/selection menu UI needs to fit the SplashKit design (palette, consistent with + existing SplashKit style (matches website style, etc) +- UI should be user friendly + +## Analytics considerations + +Comparison of different game functionality and time management, upload/download statistics? + +## Regulation & Compliance considerations + +- Secure channels, hardware safety, adequate encryptions and system protection. +- User and publisher consent + +## Operation/Training/Support considerations + +Team members will need to become familiar with SplashKit, C++, potentially Clang (compiler). Advise +teams 2 weeks in advance of planned release + +## What are the challenges? + +- Existing skill gaps (team members needing to learn new languages). +- Creating the physical arcade while remote (for later stages – can't currently implement physical + arcade aspect) +- Creating a game without knowing physical requirements + +## Acceptance criteria + +- Successful execution of building arcade (a user should be able to select and play a game to + completion on a physical arcade machine) +- Functional game (written using SplashKit) +- Step by step guide on how to create game +- Channel exists for users to upload/download validated games diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Adding Games.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Adding Games.md new file mode 100644 index 00000000..9fe79cb4 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Adding Games.md @@ -0,0 +1,169 @@ +# Adding Games to Arcade Machine + +> many of these steps are eser to perform via the GUI all commands below are for CLI but can start +> the GUI by typing `startx` in the terminal + +## C++ Programs + +> If you have a complied arm program skip to step 7 + +1. Open Terminal +2. Change to the Games Source Folder in the home directory + ``` + cd GameSource + ``` +3. Create a new folder for your Game and change into the folder (Optional) + ``` + mkdir mygame + cd mygame + ``` +4. Git Clone your code into the directory + ``` + git clone https://github.com/Thoth-Tech/MyGame.git + ``` +5. Compile your game + ``` + skm g++ program.cpp -o MyGame + ``` +6. Test Your game is running correctly (optional) + ``` + ./MyGame + ``` +7. Copy your Complied game to the Games directory\ + ``` + cp -r ~/GamesSource/MyGame ~/Games + ``` +8. Create a Launch Script for your game + ``` + nano ~Games/LaunchScript/MyGame.sh + ``` + - Add the following + ``` + #!/bin/bash + ~/Games/MyGame/MyGame + ``` + - > Note: Some C++ programs may not run correctly when executed from a remote directory in which + > case make the script chagne to the program directory first + ``` + #!/bin/bash + cd ~/Games/MyGame/ + ./MyGame + ``` + +- save by pressing `ctrl-o` and exit by pressing `ctrl-x` + +9. Make the script executable + +``` +sudo chmod +x MyGame.sh +``` + +10. Add the game to the emulation station game list. + +``` +nano ~/.emulationstation/gamelist/pc/gamelist.xml +``` + +11. Create new entire for your game. + +``` + + ./MyGame.sh + My Game + ~/Games/MyGame/TitleImage.png + +``` + +## C# Programs + +1. Open Terminal +2. Change to the Games Source Folder in the home directory + +``` +cd GameSource +``` + +3. Create a new folder for your Game and change into the folder (Optional) + +``` +mkdir mygame +cd mygame +``` + +4. Git Clone your code into the directory + +``` +git clone https://github.com/Thoth-Tech/MyGame.git +``` + +5. Compile your game (--sc complies it as standard alone) + + - you may need to change into a sub directory first + + > Compiling as a standalone program is presently required for C# games as dotnet and splashkit + > paths are not loaded on CLI boot, paths are presently loaded by bashrc which only run on + > interactive login shells. i.e. when you login to the desktop. + +``` +skm dotnet publish --sc +``` + +6. Copy libsplashkit.dll and libsplashkit.so to your published project directory + +``` +cp ~/.splaskkit/lib/linux/libsplashkit.dll ~/GamesSource/MyGame/bin/Debug/netcoreapp7.0/publish +cp ~/.splaskkit/lib/linux/libsplashkit.so ~/GamesSource/MyGame/bin/Debug/netcoreapp7.0/publish +``` + +7. Test Your game is running correctly (optional) + + - change into the publish directory + - If you are using a Resources folder copy that into the Publish directory + `cp -r ~/GamesSource/MyGame/Resources ~/GamesSource/MyGame/bin/Debug/netcoreapp7.0/publish` + +``` +./MyGame +``` + +8. Copy your Complied game to the Games directory + +``` +cp -r ~/GamesSource/MyGame/bin/Debug/netcoreapp7.0/publish/ ~/Games/MyGame +``` + +9. Create a Launch Script for your game + +``` +nano ~Games/LaunchScript/MyGame.sh +``` + +- Add the following + +``` +#!/bin/bash +~/Games/MyGame/MyGame +``` + +- save by pressing `ctrl-o` and exit by pressing `ctrl-x` + +10. Make the script executable + +``` +sudo chmod +x MyGame.sh +``` + +11. Add the game to the emulation station game list. + +``` +nano ~/.emulationstation/gamelist/pc/gamelist.xml +``` + +12. Create new entire for your game. + +``` + + ./MyGame.sh + My Game + ~/Games/MyGame/TitleImage.png + +``` diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/CreatePiImage.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/CreatePiImage.md new file mode 100644 index 00000000..22283543 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/CreatePiImage.md @@ -0,0 +1,74 @@ +## Intorduction + +This document will outline how to create a compressed disk image of the Rasberry Pi that can then be +burnt to new SD cards using the [Raspberry Pi imager](https://www.raspberrypi.com/software/) or a +program like [etcher](https://etcher.balena.io/). Using this process, you can make new Gold Images +and backups of the running software for the Arcade Machines. This process uses a script called +PiShirnk https://github.com/Drewsif/PiShrink + +The process was derived from this article: +https://www.tomshardware.com/how-to/back-up-raspberry-pi-as-disk-image + +### Current Compressed Gold Image + +https://deakin365.sharepoint.com/:u:/r/sites/ThothTech2/Shared%20Documents/SplashKit/Arcade%20Machine%20Image/ArcadeImage-19.08.2023.img.gz?csf=1&web=1&e=SdRhVX + +The current Compressed Gold Image is on the Thoth Tech Teams SharePoint Site. This is persistent but +only accessible to Thoth Tech team members. + +## Requirements + +- USB Key larger capacity than current SD Card in Pi +- Raspberry Pi with Arcade image + +Note it is possible to change the partition sizes on the Pi to use a smaller USB key, but I have not +tested that process, and it is beyond the scope of this document. If you need that process, please +refer to the Toms Hardware article above, and if successful, please update this document with the +additional optional process. + +## Create Disk Image + +1. Format USB key + - Format the USB Key as either NTFS (if using Windows) or EXT4 (if using Linux); I'm not sure + what is best for Mac OS. (This Wiki How Article explains how to format a key on Windows + https://www.wikihow.com/Format-a-Flash-Drive) +1. Connect the USB key to the Pi + + ![Image of Pi with a USB key](Images/PI_USB.jpg) + +1. On the Pi, open a terminal and run the following to install pishrink.sh and move it to + /usr/local/bin + ``` + wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh + sudo chmod +x pishrink.sh + sudo mv pishrink.sh /usr/local/bin + ``` +1. Check the mount point of the USB Key with this command + + ``` + lsblk + ``` + + ![Screen shot of the output of the lsblk command](Images/Command_lsblk.png) + + You should be able to see the mount point for the USB ours has been mounted at + `/media/deakin/Spare` (Spare is the volume name set during formatting) + +1. Copy the current SD card to the USB as an image file, i.e. my command was + `sudo dd if=/dev/mmcblk0 of=/media/deakin/Spare/ArcadeImage-19.08.2023.img bs=1M` Set the + filename as you see fit but if updating the gold image suggest using a date or version number. + ``` + sudo dd if=/dev/mmcblk0 of=[mount point]/myimg.img bs=1M + ``` +1. Move to the USB root directory, i.e. my command `cd /media/deakin/Spare` + ``` + cd cd /media/pi/[volume] + ``` +1. Run pishrink with -z option; this will zip the image with gzip. + ``` + sudo pishrink.sh -z ArcadeImage-19.08.2023.img + ``` + +You should now have a compressed image file, i.e. `ArcadeImage-19.08.2023.img.gz` refer to +[Setup Arcade Machine.md](Setup%20Arcade%20Machine.md) for instructions on burning the image to a +new SD card or USB. diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/es_systems.cfg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/es_systems.cfg new file mode 100644 index 00000000..421b3d9e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/es_systems.cfg @@ -0,0 +1,36 @@ + + + + + + + + pc + + + PC + + + /home/deakin/Games/LaunchScripts + + + .exe .sh + + + %ROM% + + + PC + + + N64 + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/OPENSANS-LIGHT.TTF b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/OPENSANS-LIGHT.TTF new file mode 100644 index 00000000..0d381897 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/OPENSANS-LIGHT.TTF differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/OPENSANS.TTF b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/OPENSANS.TTF new file mode 100644 index 00000000..db433349 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/OPENSANS.TTF differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/bright.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/bright.png new file mode 100644 index 00000000..68681baa Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/bright.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/dark.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/dark.png new file mode 100644 index 00000000..68681baa Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/dark.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/mid.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/mid.png new file mode 100644 index 00000000..64e5133b Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/mid.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_filled_spacing.svg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_filled_spacing.svg new file mode 100644 index 00000000..f6aab18c --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_filled_spacing.svg @@ -0,0 +1,12 @@ + + + + + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_2_spacing.svg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_2_spacing.svg new file mode 100644 index 00000000..75d1c25c --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_2_spacing.svg @@ -0,0 +1,21 @@ + + + + + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_3_spacing.svg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_3_spacing.svg new file mode 100644 index 00000000..c6ce4fa8 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_3_spacing.svg @@ -0,0 +1,21 @@ + + + + + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_spacing.svg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_spacing.svg new file mode 100644 index 00000000..d1063e40 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/star_hollow_spacing.svg @@ -0,0 +1,18 @@ + + + + + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/white.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/white.png new file mode 100644 index 00000000..b187f791 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/art/white.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/simple.xml b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/simple.xml new file mode 100644 index 00000000..08ba2414 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/simple.xml @@ -0,0 +1,121 @@ + + + + 3 + + + + + 0 1 + 0.5 0.5 + 0.5 0.5 + + + + + + + 393a3b + 1 + ./art/OPENSANS-LIGHT.TTF + 0.03 + 0.12 0.04 + + + + 393a3b + 1 + ./art/OPENSANS-LIGHT.TTF + 0.03 + 0.14 0.04 + + + + 393a3b + 1 + ./art/OPENSANS-LIGHT.TTF + 0.03 + + + + 393a3b + 1 + ./art/OPENSANS-LIGHT.TTF + 0.03 + 0 0.04 + + + + 0 0 + 0 0 + 1 0.16 + ./art/bright.png + + + + 0 1 + 0 1 + 1 0.065 + ./art/bright.png + + + + 0 0 + 0 0 + 1 1 + ./art/mid.png + + + + 393a3b + 97999b + 393a3b + 000000 + ./art/OPENSANS.TTF + 0.03 + 1 + + + + + + + + + + + + + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/background.jpg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/background.jpg new file mode 100644 index 00000000..b3795a0f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/background.jpg differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/backgroundprogress.pdn b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/backgroundprogress.pdn new file mode 100644 index 00000000..8cdccf3a Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/backgroundprogress.pdn differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/font.PNG b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/font.PNG new file mode 100644 index 00000000..8f8b1774 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/font.PNG differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/logotext.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/logotext.png new file mode 100644 index 00000000..02d99a82 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/logotext.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/splashkit.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/splashkit.png new file mode 100644 index 00000000..06dcae37 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/splashkit.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/thoth_artwork.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/thoth_artwork.png new file mode 100644 index 00000000..759b031c Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/thoth_artwork.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/thothlogo.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/thothlogo.png new file mode 100644 index 00000000..df5e1635 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/art/thothlogo.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/theme.xml b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/theme.xml new file mode 100644 index 00000000..855b9831 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Files/themes/splashkit/sk/theme.xml @@ -0,0 +1,161 @@ + + 3 + ./../simple.xml + + + + + ./art/background.jpg + + + + ./art/logotext.png + + + + ffffff88 + ffffff88 + + + + + + + + Splashkit + 1 + 0.45 0.08 + 0.527 0.04 + F5A623 + ./../art/OPENSANS-LIGHT.TTF + 0.055 + right + + + + + ./art/logotext.png + 0.025 0.079 + 0.47 0.1 + 0 0.5 + + + + + + + + 0.025 0.22 + 0.950 0.68 + center + 0.01 + + + + + + + + + + 0.025 0.22 + 0.12 0.301 + 0 0 + + + + 0.172 0.21 + + + + 0.172 0.25 + + + + 0.172 0.29 + 0.133 0.04 + + + + 0.172 0.33 + 0.133 0.04 + + + + 0.172 0.37 + + + + 0.172 0.41 + + + + 0.172 0.45 + + + + 0.172 0.49 + + + + 0.305 0.49 + + + + 0.305 0.45 + + + + 0.305 0.41 + + + + 0.305 0.37 + 0.25 0.04 + + + + 0.305 0.33 + 0.25 0.04 + + + + 0.305 0.29 + 0.25 0.04 + + + + 0.305 0.25 + + + + 0.305 0.216 + 0.028 0.028 + ./../art/star_filled_spacing.svg + ./../art/star_hollow_3_spacing.svg + + + + 0.52 0.3 + 0.025 0.577 + + + + 0.615 0.22 + 0.359 0.68 + left + 0.01 + + + + + diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/AdvancedOptions.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/AdvancedOptions.png new file mode 100644 index 00000000..f18b0ceb Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/AdvancedOptions.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ArcadeControls.jpg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ArcadeControls.jpg new file mode 100644 index 00000000..90d3f6b7 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ArcadeControls.jpg differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/BootAutoLogin.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/BootAutoLogin.png new file mode 100644 index 00000000..8522a8cf Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/BootAutoLogin.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/Command_lsblk.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/Command_lsblk.png new file mode 100644 index 00000000..ca31e838 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/Command_lsblk.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ConfigureInput.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ConfigureInput.png new file mode 100644 index 00000000..daf80c1b Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ConfigureInput.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ConsoleAutologin.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ConsoleAutologin.png new file mode 100644 index 00000000..1b3fba78 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ConsoleAutologin.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/CorePackage.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/CorePackage.png new file mode 100644 index 00000000..c624986d Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/CorePackage.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/EmulationStation.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/EmulationStation.png new file mode 100644 index 00000000..80b3261a Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/EmulationStation.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/EnableSSH.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/EnableSSH.png new file mode 100644 index 00000000..86edf5b5 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/EnableSSH.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/InterfaceOptions.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/InterfaceOptions.png new file mode 100644 index 00000000..55716170 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/InterfaceOptions.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ManagePackage.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ManagePackage.png new file mode 100644 index 00000000..57e56029 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ManagePackage.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/NetworkConfig.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/NetworkConfig.png new file mode 100644 index 00000000..7c167b2c Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/NetworkConfig.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/NetworkManager.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/NetworkManager.png new file mode 100644 index 00000000..99fbf4fa Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/NetworkManager.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/PI_USB.jpg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/PI_USB.jpg new file mode 100644 index 00000000..a7ecbd2d Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/PI_USB.jpg differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigAutostart.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigAutostart.png new file mode 100644 index 00000000..23e6720c Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigAutostart.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigStartEmulationStation.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigStartEmulationStation.png new file mode 100644 index 00000000..f6921629 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigStartEmulationStation.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigTools.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigTools.png new file mode 100644 index 00000000..47ecf1cb Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/RetroPiConfigTools.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SSHEnableScreen.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SSHEnableScreen.png new file mode 100644 index 00000000..a369e69f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SSHEnableScreen.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ScreenShotEtcher.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ScreenShotEtcher.png new file mode 100644 index 00000000..c0131cd4 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/ScreenShotEtcher.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SetKeys.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SetKeys.png new file mode 100644 index 00000000..67241ee6 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SetKeys.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SettingsThemeSelection.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SettingsThemeSelection.png new file mode 100644 index 00000000..7fee2492 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SettingsThemeSelection.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/StartOnSystem.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/StartOnSystem.png new file mode 100644 index 00000000..67d3e4f3 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/StartOnSystem.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SystemOptions.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SystemOptions.png new file mode 100644 index 00000000..a7f11771 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SystemOptions.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SystemThemeSetup.jpg b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SystemThemeSetup.jpg new file mode 100644 index 00000000..c6380630 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Images/SystemThemeSetup.jpg differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Setup Arcade Machine.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Setup Arcade Machine.md new file mode 100644 index 00000000..eccac4d1 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Arcade Machine Setup/Setup Arcade Machine.md @@ -0,0 +1,400 @@ +# How to setup Arcade Machine + +## Existing Image + +Download current arcade Image from here (accessible to Thoth-Tech Team Members): + + +SHA256 Hash `31f0ea11c8492000d003108bf84afbb261ad6ee7c1be989f52a2b4add9d8821e` + +Use a program like [etcher](https://etcher.balena.io/) to create a bootable USB or SD card with the +Arcade image. + +1. Open etcher +2. Select image +3. select target USB or SD Card +4. Click FLASH + ![Image of the program etcher](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/ScreenShotEtcher.png) + + +These are the Credentials setup on the image + +1. Local User Name: `deakin` Password: `qwerty` +2. SSH Uses Local user name and password +3. SMB Share uses Name `deakin` password `deakin` +4. WiFi SSID `Arcade1` Password `GamesAreFun` + +## Manual Setup + +### Load OS + +1. Install Raspberry Pi OS + - Detailed instructions on installing Raspberry Pi OS On a USB available + [here](https://pimylifeup.com/raspberry-pi-boot-from-usb/). +2. Plug USB into PI or Arcade Machine and follow the setup wizard + - Current username and password are `deakin` and `qwerty` +3. Update all Software to the latestes version + +## Connect to eduroam + +Two changes need to be made to allow the Pi to access the eduroam network. One to network interfaces +and one to wpa_supplicant: + +1. Modify /etc/network/interfaces to bring the wlan0 interface up automatically, use DHCP and read + from the wpa_supplicant config + + - From the console open the interfaces file: + + ```shell + sudo nano /etc/network/interfaces + ``` + + - Copy the following text to the **bottom** of the interfaces file + + ```plaintext + allow-hotplug wlan0 + iface wlan0 inet manual + wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf + iface wlan0 inet dhcp + ``` + + - Press Ctrl+X to exit and press **y** when prompted to save your changes + +2. Modify the wpa_supplicant with the custom eduroam config + + - From the console open the wpa_supplicant config file: + + ```shell + sudo nano /etc/wpa_supplicant/wpa_supplicant.conf + ``` + + - Copy the following text into the wpa_supplicant file + + ```plaintext + ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev + update_config=1 + + network={ + ssid="eduroam" + priority=1 + proto=RSN + key_mgmt=WPA-EAP + pairwise=CCMP + auth_alg=OPEN + eap=PEAP + identity="YOURUSERNAME@deakin.edu.au" + password="YOURPASSWORD" + phase1="peaplabel=0" + phase2="auth=MSCHAPV2" + } + ``` + + - Replace **YOURUSERNAME** and **YOURPASSWORD** with the arcade machine's eduroam login + credentials. Ensure you include the domain I.E. "" + - Press Ctrl+X to exit and press **y** when prompted to save your changes. + +3. Reboot and test network connectivity + + - Reboot the Raspberry Pi by issuing the below command: + + ```shell + sudo reboot + ``` + + - Test network connectivity by pinging an external site, for example Google's DNS: + + ```shell + ping 8.8.8.8 + ``` + +## Install Software + +### 1. Install SplashKit + +- Follow the instructions [here](https://splashkit.io/articles/installation/ubuntu/). +- Primarly perform steps 1 and 2, VS code is optional unless you whish to adjust programming on the + PI directly. + +### 2. Install .NET (dotnet) + +- You can refer to [this page](https://learn.microsoft.com/en-us/dotnet/iot/deployment) but these + are the core commands: + + 1. Run this install script + + ```shell + curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel STS + ``` + + 2. Add the following to the end of the file `~/.bashrc` with these commands + + ```shell + echo 'export DOTNET_ROOT=$HOME/.dotnet' >> ~/.bashrc + echo 'export PATH=$PATH:$HOME/.dotnet' >> ~/.bashrc + source ~/.bashrc + ``` + + 3. Verify the insalation with this command + + ```shell + dotnet --version + ``` + +### 3. Install Git + +- Run the following command + + ```shell + sudo apt update + sudo apt install git + ``` + +### 4. Install Emulation Station (using RetroPi) + +1. git clone retroPI setup + + ```shell + git clone --depth=1 https://github.com/RetroPie/RetroPie-Setup.git + ``` + +2. Run the setup script + + ```shell + cd RetroPie-Setup + sudo ./retropie_setup.sh + ``` + +3. Select manage packages + + ![RetorPie setup Main scree](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/ManagePackage.png) + +4. Select core + + ![RetorPie setup Manage Packages scree](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/CorePackage.png) + +5. Select emulationstation + + ![RetorPie setup Manage Packages scree](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/EmulationStation.png) + +6. Exit retroPie setup +7. Create Emulation Station es_systems.cfg file + + ```shell + nano ~/.emulationstation/es_systems.cfg + ``` + +8. Add the following to the file or downlaod a copy from + [here](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Files/es_systems.cfg) + + ```config + + + + + + + + pc + + + PC + + + /home/deakin/Games/LaunchScripts + + + .exe .sh + + + %ROM% + + + PC + + + N64 + + + ``` + +9. Create a folder for the games + + ```shell + mkdir ~/Games + ``` + +10. Create a folder for the launch scripts + + ```shell + mkdir ~/Games/LaunchScripts + ``` + +## Configure Software + +### Configure Emulation Station + +1. Start Emulation Station enter the following command: + + ```shell + emulationstation + ``` + +2. First time setup you will need to configure the controller + + 1. Hold Down any key to start + + ![EmulationStation Configure Input Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/ConfigureInput.png) + + 2. Press any key to configure input + + Recommend the Following for the Arcade Machine the rest can be skipped + + - up = up arrow + - down = down arrow + - left = left arrow + - right = right arrow + - start = escape + - select = enter + - A = left control + - B = left alt + + ![Input Selection Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/SetKeys.png) + + 3. It will note a hotkey was not selected say yes to accept using select + +3. Press Escape to bring up the menu +4. Select UI Settings +5. Scroll down to start on system and set it to PC + + ![UI Settings Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/StartOnSystem.png) + +6. Go back and Quit Emulation Station + +### Configure Start CLI on Boot and Network Manager + +1. Launch Rasberry Pi Configuration + + ```shell + sudo raspi-config + ``` + +2. Select System Options + + ![Rasberry Pi Configuration Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/SystemOptions.png) + +3. Select Boot / Auto Login + + ![Rasberry Pi system Option Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/BootAutoLogin.png) + +4. Select Console Autologin + + ![Rasberry Pi Boot Option Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/ConsoleAutoLogin.png) + +5. Return to main menu +6. Select Advanced Options + + ![Rasberry Pi Configuration Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/AdvancedOptions.png) + +7. Select Network Config + + ![Rasberry Pi Configuration Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/NetworkConfig.png) + +8. Select Network Manager + + ![Rasberry Pi Configuration Screen](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/NetworkManager.png) + +9. Select OK +10. Select Interface Options + + ![Rasberry Pi Configuration Screen with interface options selected](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/InterfaceOptions.png) + +11. Select SSH + + ![Rasberry Pi Configuration Screen with SSH selected](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/EnableSSH.png) + +12. Select Yes + + ![Rasberry Pi Configuration Screen with Yes selected](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/SSHEnableScreen.png) + +13. Select Ok and Finshed to exit Rasberry Pi Configuration +14. You can reboot now or later + +### Setup WiFi Access Point (Optional) + +This will set the PI up as a WiFi Access Point so you can SSH in when the USB ports are not +accessible. + +[Basic Guide Availble Here](https://gist.github.com/narate/d3f001c97e1c981a59f94cd76f041140) + +Enter the following commands, the SSID is set to Arcade1 - change the number for the machine you are +working on. + +```shell +nmcli con add type wifi ifname wlan0 con-name Hostspot autoconnect yes ssid Arcade1 +nmcli con modify Hostspot 802-11-wireless.mode ap 802-11-wireless.band bg ipv4.method shared +nmcli con modify Hostspot wifi-sec.key-mgmt wpa-psk +nmcli con modify Hostspot wifi-sec.psk "GamesAreFun" +nmcli con up Hostspot +``` + +The Pi will now be broadcasting a WiFi network called Arcade1 with the password GamesAreFun + +- The IP address of the Pi will be 10.42.0.1/24 this current setup does not allow for DHCP so any +- connecting client will need to manually set an IP address in use the following settings: + + IP Address: 10.42.0.2 Subnet Mask: 255.255.255.0 Gateway: 10.42.0.1 + +### Set Emulation Station as the Default Shell + +1. Change to the Retro Pi Setup Folder + + ```shell + cd ~/RetroPie-Setup + ``` + +2. Run the Retro Pi Setup Script + + ```shell + sudo ./retropie_setup.sh + ``` + +3. Select Configuration / Tools + + ![RetroPi Config Screen with Configuration / Tools selected](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/RetroPiConfigTools.png) + +4. Select Autostart + + ![RetroPi Config Screen with Autostart selected](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/RetroPiConfigAutostart.png) + +5. Select Start Emulation Station at boot + + ![RetroPi Config Screen with Start Emulation Station at boot selected](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/RetroPiConfigStartEmulationStation.png) + +6. Select Ok +7. Select Finish +8. Select Perform Reboot + +## Installing the Splashkit Theme + +1. Download the Themes folder located at: docs/Splashkit/Applications/Arcade Machines/Arcade Machine + Setup/Files + +2. Copy the Themes folder into your .emulationstation folder, located at ~/.emulationstation on the + Raspberry Pi or at %HOMEPATH%/.emulationstation on windows devices. + +3. In the es_systems.cfg file, located in the file paths mentioned in step 2, you will need to + change the XML code for the theme to be "sk." + + ![es_systems.cfg file open showing where to change the theme](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/SystemThemeSetup.jpg) + +4. Launch EmulationStation, open the start menu, and under UI settings change Theme set to + "Splashkit." + + ![Theme Set selection in EmulationStation](/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Images/SettingsThemeSelection.png) diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/Contributors Guide.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/Contributors Guide.md new file mode 100644 index 00000000..f9319dd9 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/Contributors Guide.md @@ -0,0 +1,155 @@ +# Guide to Contribute a Game to the Arcade Machine + +This guide takes you through the steps required for your game to be added into the arcade-machine +library. + +- [Coding](#coding) + - [Quit Request](#quit-request) + - [Window Size](#window-size) + - [Window Border](#window-border) +- [Controls](#controls) +- [Compiling](#compiling) +- [Artwork](#artwork) +- [Configuration](#configuration) +- [Content](#content) +- [Contributing](#contributing) + +## Coding + +To make the game accessible and controllable by the arcade machine, some additional code or changes +are required. + +### Quit Request + +Your game must be able to be exited using the escape key. This can be achieved by including the +following command in your main loop. + +```cpp +int main() +{ + while(!key_down(ESCAPE_KEY)) + { + // game play + } +} +``` + +### Window Size + +The window size of your game cannot exceed 1600 x 900, this is to allow your game to sit neatly +inside the arcade-machine itself. Similarly, there is a minimum window size of 640 x 480, to ensure +visibility for the user. + +The window size of your game cannot exceed 1600 x 900, this is to allow your game to sit neatly +inside the arcade-machine itself. Similarly, but mainly for aesthetic purposes, a minimum window +size of 640 x 480 is expected. + +### Window Border + +We ask that you remove the border before compiling your game. The Arcade Machine provides a more +immersive experience for the user if there is no border. To remove the border of your game window, +use SplashKit’s `window_toggle_border();` function after the `open_window()` function like so: + +```cpp +int main() +{ + open_window("my game", width, height); + window_toggle_border("my game"); +} +``` + +## Controls + +(TBA - Missing content) + +## Compiling + +Only Windows compiled games are supported at the moment. + +(TBA - Brief windows compilation explanation) + +## Artwork + +A preview of your game will be shown in the Arcade Machine games menu. + +(TBA - Please include an image of your game) + +This image must be sized as 600px x 540px so it will be displayed correctly in the games menu. The +supported formats are `png`, `jpg` and `bmp`. + +If you don’t have access to image editing software such as Adobe Illustrator/Photoshop, we suggest +you use a browser-based tool such as [resizeimage](https://resizeimage.net/) to resize, crop or +format a screenshot of your game. + +## Configuration + +Each game must have a configuration file containing information about the game. There is a +`config.txt` file located in the base directory of the repository, copy this file into the base +directory of your game file and fill it with your game information. It must match the example +configuration file shown below, but with your game information. + +![image](images/config-data.png) + +The configuration file **must** be in text (`.txt`) format, and it must be named `config.txt`. This +must be located in your games root directory, alongside your `program.cpp` (example below). + +![image](images/dir-breakdown.png) + +## Content + +(TBA - explanation of content requirements) + +## Contributing + +Congratulations! + +You have now completed all the steps required to have your game showcased on the Arcade Machine. + +To contribute your game, go to the +[Thoth Tech arcade-games repository](https://github.com/thoth-tech/arcade-games). Click the **Fork** +button at the top right of the screen and create a fork of this repository. + +![image](images/fork-repo.png) + +You will now have the arcade-games repository in your personal Git. + +![image](images/forked.png) + +On your local, navigate to a desired file path and clone this repository using the bash command: + +```shell +git clone https://github.com//arcade-games.git +``` + +Add your game to the directory and stage a commit to the remote repository: + +```shell +git add . +``` + +In your commit message, include your name and the name of the game: + +```shell +git commit -m ”Anthony George - Venture Adventure” +git push +``` + +You will now see your game in the remote fork. + +![image](images/commit.png) + +Now create a Pull request to have your game added to the arcade-machine. + +Click the **Pull requests** tab, then click **New pull request** button, then click **Create pull +request** + +![image](images/pull-request.png) + +Write a message for the Arcade Machine and hit **Create pull request** + +![image](images/pull-request-2.png) + +You will see that merging is blocked until a member of the Arcade-Machine team has reviewed your +game. We will be sure to get in contact with you once it has been approved! + +![image](images/review.png) diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/commit.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/commit.png new file mode 100644 index 00000000..b69e0a7a Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/commit.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/config-data.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/config-data.png new file mode 100644 index 00000000..d541717f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/config-data.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/dir-breakdown.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/dir-breakdown.png new file mode 100644 index 00000000..4d3d4a66 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/dir-breakdown.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/fork-repo.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/fork-repo.png new file mode 100644 index 00000000..c69b3da4 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/fork-repo.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/forked.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/forked.png new file mode 100644 index 00000000..2b94b5cf Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/forked.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/pull-request-2.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/pull-request-2.png new file mode 100644 index 00000000..8545383a Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/pull-request-2.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/pull-request.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/pull-request.png new file mode 100644 index 00000000..b86480b4 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/pull-request.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/review.png b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/review.png new file mode 100644 index 00000000..71e2909d Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Arcade Machines/Guide to Contribute a Game/images/review.png differ diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Index.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Index.md new file mode 100644 index 00000000..976c6657 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Index.md @@ -0,0 +1,3 @@ +# Research & Findings + +This folder contains research insights, technical findings, and notes related to the development of Splashkit applications. Use this section to explore challenges, ideas, and experimental documentation. diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Add_second_controller_findings.mdx b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Add_second_controller_findings.mdx new file mode 100644 index 00000000..dee56d88 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Add_second_controller_findings.mdx @@ -0,0 +1,99 @@ +# Emulation Station - Allow both users to control emulationstation menus + +## Background +The arcade machine uses a bespoke controller for input. The controller hardware uses JoyToKey to remap joypad inputs to a emulated keyboard. Both players have separate physical controls, but the arcade sees this as a single unified keyboard. + +The user interface uses a program called emulationstation, which is in turn integrated into RetroPie. + +This has the effect of only allowing a single user to control the menu outside of games (in emulationstation). An enhancement request has been raised to add functionality where both players can control menus. + + +### Findings: + +- Linux is only able to interact with a single keyboard. It is not possible to have two hardware keyboards, and use both for input. + +- The desired functionality **is** possible with two discrete controllers. If the user connects and configures two controllers to the arcade machine, both players will be able to interact with menus independent of each other. This has been tested locally with me using a PlayStation 4 & PlayStation 5 controller connected via USB. + - It is also possible to use one keyboard and one controller, and have each device represent input for each player + +- RetroPie & EmulationStation handle input differently. + - Emulationstation configs do not discriminate between player 1 and player 2 (or any number of players). Rather the config is just a series of buttons mapped to inputs. + - Config file: `/home/$username/.emulationstation/es_input.cfg` + + - RetroPie **does** discriminate between players. Inputs are named player1_up, player1_down etc. + - Creating additional lines in the config file for player2 controls does not affect Emulationstation I.E. + - `player1_button_up="a", player2_button_up="z"` + - Config file: `/opt/retropie/configs/all/retroarch.cfg` + +- Modifying the Retropie config file directly does not change the Emulationstation controls. +- Modifying the EmulationStation config directly breaks input when the program is next started. + - This can be fixed by resetting the config + - Running the script declared in this config file does not appear to update the config either + - Shell script path: `/opt/retropie/supplementary/emulationstation/scripts/inputconfiguration.sh` + - In order to actually update the config it seems necessary to use the input confg wizard in the GUI. + + +### Emulationstation input config file: +Emulationstation holds configuration settings for user input devices in a file located here: `/home/$username/.emulationstation/es_input.cfg`. This is an XML formatted file. Each device type creates it's own "inputConfig" section. The `id` refers to the decimal [ASCII character code](https://www.ascii-code.com/). E.G lowercase "a" has a decimal value of 97 (0x61). + +An example config file looks like this: +``` + + + + /opt/retropie/supplementary/emulationstation/scripts/inputconfiguration.sh + + + + + + + + + + + + + + +``` + +The section for controller iput looks like this: +``` + + + + +``` + +Adding multiple "inputConfig" sections for keyboards does not work. I.E: +``` + + + + + + +``` + +### Outcome: +It does not appear to be possible to implement this functionality given the current state of constituent systems & hardware limitations of the Linux kernel without significantly reworking other aspects of the Arcade Machine's hardware & software configuration. + +#### Main limiting factors are: + - Inability to address two keyboards concurrently - This is extremely unlikely to change, and very difficult to work around + - Limitations in ability to modify EmulationStation configs to suit arcade machine needs + - System configuration is brittle - manually editing many of RetroPie (or constituent) configs will silently break functionality + - Existing dependence on handling Arcade Machine input as an emulated keyboard + +### Recommendations: +I would assess this enhancement as "low priority" in the grander scheme of the project. To be clear, dual user input is currently supported within SplashKit games themselves. This limitation only affects the EmulationStation overlay. Which essentially means that only player 1 has control over this menu. + +If this is deemed to be a requirement then I would recommend removing JoyToKey from the arcade machine and handling input directly as a joypad. This would also require bifurcating the two joypads into two discrete devices. As mentioned above, this would require a rework of several other systems to accommodate this change. In addition many SplashKit games would need to be reworked to handle joypad input, as most currently use Keyboard input only. + +### Links: +[Thoth-Tech doc on Arcade Machine setup](https://github.com/thoth-tech/documentation/blob/main/docs/Splashkit/Applications/Arcade%20Machines/Arcade%20Machine%20Setup/Setup%20Arcade%20Machine.md) + +[RetroPie controller documentation](https://retropie.org.uk/docs/RetroArch-Configuration/#hardcoded-configurations) + +[Configuring controls in Retropie](https://retropie.org.uk/docs/Controller-Configuration/) + +[Example EmulationStation es_input_cfg file](https://gist.github.com/neolao/e4d5960c4ee1e8ed5291) diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Asteroids Game Test Report b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Asteroids Game Test Report new file mode 100644 index 00000000..be793c4e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Asteroids Game Test Report @@ -0,0 +1,74 @@ +# Asteroids Game Test Report +Date of Testing: [20/08/2023] + +## Executive Summary + +This report outlines the findings from the testing of the Asteroids,The testing process aimed to identify and address potential issues affecting gameplay, graphics, performance, user interface, and overall user experience. One significant issue identified is the excessive speed of meteorites, which has a notable impact on the game's difficulty and player engagement. + +## Testing Goals + +- Evaluate gameplay mechanics and balance. +- Assess graphics quality and performance. +- Test user interface design and intuitiveness. +- Identify and report bugs and usability issues. + +## Testing Environment + +- Testing Tools: Arcade machine + +## Test Cases + +The following test cases were executed during the testing phase: + +### Test Case 1: Meteorite Speed +- Description: Evaluate the speed of meteorites during gameplay. +- Steps to Reproduce: +1. Launch the game. +2. Start a new game session. +3. Observe the speed at which meteorites move across the screen. +- Expected Result: Meteorite speed is challenging yet manageable, allowing players to navigate effectively. +- Actual Result: Meteorites move at an excessive speed, making it difficult for players to react and avoid collisions. + +## Bugs/Issues + +### Issue: Excessive Meteorite Speed +- Description: During gameplay, it was observed that the meteorites move at an excessively high speed, leading to an increase in game difficulty beyond the intended level. +- Steps to Reproduce: +1. Launch the game. +2. Start a new game session. +3. Observe the speed at which meteorites move across the screen. + +- Notes: The rapid movement of meteorites makes it challenging for players to react and navigate effectively, impacting the overall gameplay experience. This issue is particularly noticeable on higher levels, where it becomes nearly impossible to avoid collisions due to the meteorites' speed. + +**Proposed Solution:** +The meteorite speed needs to be adjusted to provide players with a fair and engaging gameplay experience. By reducing the speed to a more manageable level, players will have better control over their ship's movements and can effectively strategize to avoid collisions. This adjustment will maintain a challenging aspect while not compromising the core enjoyment of the game. + +**Testing Required:** +1. Implement adjustments to meteorite speed. +2. Conduct thorough playtesting to ensure the new speed level provides an appropriate balance of challenge and enjoyment. +3. Gather player feedback to validate the changes and assess whether the meteorite movement feels more balanced. + +**Impact:** +This issue significantly affects the game's playability and enjoyment. Addressing the meteorite speed will enhance the overall experience and encourage players to engage with the game for longer periods. Failure to address this issue could result in player frustration, leading to reduced player retention and potential negative reviews. + +## Performance Evaluation + +Performance evaluation revealed no significant issues. The game maintained a stable frame rate even during intense gameplay moments, and load times were within acceptable limits. + +## User Experience (UX) Evaluation + +The overall user experience was positive. However, the excessive meteorite speed issue has negatively impacted the user experience by making the game overly challenging. + +## Suggestions and Feedback + +- Address the excessive meteorite speed issue to enhance gameplay balance. +- Visual Feedback: Provide clearer visual cues when the player's ship is hit by a meteorite. This can include visual effects, screen shakes, or sound effects to enhance the impact and improve feedback to the player. +- Power-ups and Abilities: Consider introducing power-ups or special abilities that the player can acquire during gameplay. These could include temporary shields, slow motion, or increased firepower, adding variety and strategic depth to the gameplay. + +## Conclusion + +The testing process has revealed several strengths of the Asteroids, including its intuitive controls and engaging gameplay. However, the issue of excessive meteorite speed poses a significant challenge to player enjoyment and needs to be promptly addressed. By implementing the proposed solution, the game can provide a more balanced and enjoyable experience for players. + +--- + +By [Wenxuan Song] diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Below The Surface Game Test Report b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Below The Surface Game Test Report new file mode 100644 index 00000000..72c74dd4 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Below The Surface Game Test Report @@ -0,0 +1,58 @@ +# Below The Surface Game Test Report +Date of Testing: [20/08/2023] + +## Executive Summary + +This test report outlines findings from testing the arcade game "Below the Surface." The game exhibited a critical issue when played with two players, where the movement of one player caused the screen to move, leading to the other player's death when they moved off-screen. Additionally, a suggestion was made to restrict player movements when they are positioned beyond the screen's boundaries. The report discusses the problem's impact, provides reproduction steps, and suggests potential solutions. + +## Testing Goals + +-The primary objective of testing was to assess the gameplay experience of the arcade game "Below the Surface" when played with two players simultaneously. +-The focus was on evaluating the game's screen movement behavior on the arcade machine and identifying any issues that arise as a result. + +## Testing Environment + +- Testing Tool: Arcade machine + +## Test Cases + +The following test cases were executed during the testing phase: + +### Test Case 1: 2 players movement +- Description: Play in pairs to experience the effects of player movements in 2 players mode +1. Launch the game on the arcade machine with two players. +2. Begin gameplay, with both players moving in different directions. +3. Observe what happens when two players move on the screen at the same time + +## Bugs/Issues + +### Issue: Screen Movement Causing Player Deaths +- Description: When playing with two players, the movement of one player causes the screen to shift, resulting in the other player's death if they move off-screen. +1. Launch the game on the arcade machine with two players. +2. Begin gameplay, with both players moving in different directions. +3. Observe the screen movement causing one player to be left off-screen and subsequently dying. + +**Impact:** +The issue severely hampers multiplayer gameplay, rendering it frustrating and unplayable. + +**Proposed Solution:** +The movement of the screen needs to be adjusted, and deaths should not occur because of the movement of two players when playing. This ensures the core gameplay and fun of the game. +- Improved Dual-Screen Mode: Modify the game's screen behavior to split into two distinct views when two players move in opposite directions. This would allow each player to move independently without affecting the other's gameplay. However, this solution may require significant technical adjustments and testing. +- Player Respawning Mechanism: Implement a respawning mechanism that triggers when a player moves off-screen. Upon detection of off-screen movement, the player would respawn at a safe location, ensuring they are not unfairly penalized for screen movement. +- Restrict Movement Beyond Screen Boundaries: Restrict player movements when they are positioned beyond the screen's boundaries. This would prevent screen movement caused by one player's actions and allow both players to remain on the same screen. + + +## Suggestions and Feedback +To address this issue and provide a seamless multiplayer experience, the following potential solutions are recommended: +-When the player reaches full health, he cannot pick up heart-shaped items to increase health, but can instead increase score. +-The color of the cockroach shaped monster is too dim, and the dark background is easy to cause the player to lose sight of it +-The jump rate is too fast, making the player's countermeasures against the monsters too difficult + +## Conclusion + +The critical issue of screen movement affecting multiplayer gameplay in the arcade game "Below the Surface" significantly detracts from the intended cooperative experience. The recommended solutions aim to resolve this issue and restore the game's multiplayer functionality. Implementing these solutions, along with the provided suggestions, will greatly enhance the overall enjoyment and engagement of players. + + +--- + +By [Wenxuan Song] diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Emulation Station Script Research.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Emulation Station Script Research.md new file mode 100644 index 00000000..3810622d --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Emulation Station Script Research.md @@ -0,0 +1,48 @@ +# Emulation Station Script Research + +## How to Setup A Script + +1. In your ~homepath/.emulationstation folder create a new folder named scripts + +2. within the scripts folder, using the table from + https://retropie.org.uk/docs/EmulationStation/#scripting (Under scripting > 2. Event + directories), create a new folder with the name of the event you want the script to run for. + +3. Within the event folder, you can place Shell Script files that you want to run on the event. + +### Notes + +The scripts will need testing on either a raspberry pi or a Linux pc, as windows doesn't natively +support running shell scripts. + +As shown by the table on https://retropie.org.uk/docs/EmulationStation/#scripting, depending on the +event, certain bits of data get passed along to the script. + +## Ten Minute Idle Timer + +For creating the idle timer you will most likely need to have a script running from the game-start +event, which passes down the %rom_path%, %rom_name%, and %game_name% arguments. The arcade machine +isn't using emulators testing would need to see which of these arguments can call a close on the +opened game. + +### Test Hello World Script + +Below is a test script that will create a file containing the words HELLO WORLD, the #! /bin/bash +line gives the script elevated permissions. + +#! /bin/bash + +FILE="YOUR-FILEPATH-HERE" + echo before + echo HELLO WORLD >> "$FILE" + echo "$\*" >> "$FILE" + echo after + +## Useful Links + +https://unix.stackexchange.com/questions/94322/is-it-possible-for-a-daemon-i-e-background-process-to-look-for-key-presses-fr +This is a stack exchange question looking into detecting inputs on a linux/unix device. The answers +talk about the file paths for devices and gives a sample code using C. + +https://retropie.org.uk/forum/topic/26927/emulation-game-start-scripts-folder +A forum post asking about some issues regarding a game-start script. diff --git a/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Index.md b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Index.md new file mode 100644 index 00000000..206f46a8 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Arcade Machines/Research & Findings/Index.md @@ -0,0 +1,5 @@ +# Research & Findings + +This section includes various research activities and testing documentation for Splashkit and game development projects. + +Explore game test reports, controller integration findings, and setup research for Emulation Station. diff --git a/src/content/docs/Splashkit/Applications/Assets b/src/content/docs/Splashkit/Applications/Assets new file mode 100644 index 00000000..7e7a3c5d --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Assets @@ -0,0 +1 @@ +this folder holds arcade machine image assets and game assets diff --git a/src/content/docs/Splashkit/Applications/Build a COOL game/DiceyCombat/diceycombat.cpp b/src/content/docs/Splashkit/Applications/Build a COOL game/DiceyCombat/diceycombat.cpp new file mode 100644 index 00000000..78af1bab --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Build a COOL game/DiceyCombat/diceycombat.cpp @@ -0,0 +1,275 @@ +#include "splashkit.h" +#include "all the headers" + +using namespace std; + +#define SCREEN_HEIGHT 900 +#define SCREEN_WIDTH 1600 + +void load_recourses() +{ + load images/backgrounds and sounds +} + +int main() +{ + open_window(insert game file, SCREEN_WIDTH, SCREEN_HEIGHT) + load_recourses(); + + game file = new game; + + while(game is not quit) + { + if menu is active + { + load game menu + } + else + { + draw game + insert game input handle + } + } + + return 0; +} + +//headers required to load the game, eg image assets...etc +//all headers must be in txt file + +//player header +#define the game player +#include "splashkit.h" + +using namespace std; + +#define any public variables + +player +{ + player 1 + player 2 +} + +struct player data +{ + list all the player data, if sprite is used then +} + +void handle_input(inserting player data file) + +void draw_player(insert const player data & draw player) + +#endif + + +// player cpp +#include "splashkit.h" +#include "player.h" +#include "game.h" + +bitmap player bitmap +{ + draw player 1 & 2 +} + +defining new player() +{ + load both players bitmap; + + creating sprite for player 1; + creating sprite for player 2; + + return result; +} + +void input handle(plater data & player) +{ + if analogstick is moved then + { + cursor moves + } + + if A button is pressed + { + the option is selected + } +} + +void draw player +{ + draw sprite(player sprite) +} + + +//dice roll header +#define the game player +#include "splashkit.h" + +using namespace std; + +#define any public variables + +dice +{ + dice 1 + dice 2 + dice 3 + dice 4 +} + +struct dice data +{ + defining sprites +} + +void handle_input(inserting input handling file) + +void draw_dice(insert const dice data & draw dice) + + +//dice roll cpp +#include "splashkit.h" +#include "dice.h" +#include "game.h" + +using namespace std; + +#define any public variables + +drawing dice bitmap +{ + list all the dices; +} + +void draw_dice(const dice data & dice to draw) +{ + draw sprite(dice to draw main sprite) +} + +void dice timer(dice data) +{ + defining/assigning a timer name for the time of the dice roll; + creating the timer using the above; +} + +void update dice(dice data & dice to update) +{ + applying the movement and reset of dice bitmap; + set sprites location to the updated coordinates; +} + +//game header +#define dicey game + +#include "splashkit.h" +#include "dice.h" +#include "player.h" + +#include + +using namespace std; + +struct game data +{ + list all the data; +} + +game data new_game(); + +void draw_game(constant game data & game); + +void update game(game data & game); + +void input handle(game data & game); + + +//game cpp +#include "splashkit.h" +#include "game.h" +#include "player.h" + +using namespace std; + +void add dicey game to game +{ + start new game, clear existing dicey game; + adding dicey to game dicey vector; +} + +creating new game() +{ + list all the variables and settings; +} + +void draw all elements on screen(constant game data & game) +{ + clearn screen; + draw bitmap; + draw player 1, player 2; + draw dice roll; + draw cursor; + draw indicator; + refresh screen; +} + +update all elements in game() +{ + update players location; + update indicators; + update dice roll; +} + +void input handle() +{ + button 'A' = deciding/selecting button; + analog = moving the cursor around +} + +//roll and pass header +#include "splashkit.h" +using namespace std; + +#define any public variables + +button +{ + roll; + pass; +} + +struct button data +{ + defining sprites +} + +void handle_input(inserting input handling file) + +void draw_button(insert const button data & draw button) + +//roll and pass cpp +#include "splashkit.h" +#include "dice.h" +#include "roll.h" + +using namespace std; + +bitmap player bitmap +{ + draw roll; + draw pass; +} + +void input handle(plater data & player) +{ + if analogstick is moved then pressed on roll button + { + draw sprite(dice to draw main sprite) + call timer parameter; + } + + elseif analogstick is moved then pressed on pass button + { + update player; + } +} diff --git a/src/content/docs/Splashkit/Applications/Build a COOL game/Index.md b/src/content/docs/Splashkit/Applications/Build a COOL game/Index.md new file mode 100644 index 00000000..6ae8a370 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Build a COOL game/Index.md @@ -0,0 +1,9 @@ +# Splashkit Extensions + +This folder contains documentation for Splashkit-related extensions including: +- GPIO Support +- Language Extensions +- Python Compatibility +- Debian Packaging + +Use this section to explore advanced integration topics for Splashkit. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/BelowTheSurfaceDesignDocument.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/BelowTheSurfaceDesignDocument.md new file mode 100644 index 00000000..1bdf5d97 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/BelowTheSurfaceDesignDocument.md @@ -0,0 +1,330 @@ +# Thoth Tech + +## Application Team | Build An Exception Game + +## Table of Contents + +[Name of Game](#name-of-game) + +[Genre](#genre) + +[Art Style](#art-style) + +[How the Game Works](#how-the-game-works) + +[How the Game is Played with Duos](#how-the-game-is-played-with-duos) + +[How the Game is Played Solo](#how-the-game-is-played-with-solo) + +[How the Game is Won](#how-the-game-is-won) + +[Level Plan](#level-plan) + +[How the Game is Lost](#how-the-game-is-lost) + +[Lore](#lore) + +[The Mission](#the-mission) + +[The Enemies](#the-enemies) + +[The Water Company](#the-water-company) + +[Your Tools](#your-tools) + +[Did You Know? (Loading Screen Messages)](#did-you-know-loading-screen-messages) + +[Reference Art / Early Sketches](#reference-art--early-sketches) + +[Sewer Reference Art](#sewer-reference-art) + +[Water Reference Art](#water-reference-art) + +[Pipes Early Sketch](#pipes-early-sketch) + +[Created Assets](#created-assets) + +[Appendices](#appendices) + +[Defining the Game: The Victory and Loss Conditions](#defining-the-game-the-victory-and-loss-conditions) + +[Active Challenges of the Game](#active-challenges-of-the-game) + +[Internal Economy of the Game](#internal-economy-of-the-game) + +[Describing the Rules of the Game](#describing-the-rules-of-the-game) + +[Operational Rules (Intrinsic Relationship with Constitutive Rules)](#operational-rules-intrinsic-relationship-with-constitutive-rules) + +[Constitutive Rules (Intrinsic Relationship with Operational)](#constitutive-rules-intrinsic-relationship-with-operational) + +[Implicit Rules](#implicit-rules) + +[Description of Game Mechanics using Rules](#description-of-game-mechanics-using-rules) + +[Goals](#goals) + +[Psychological Techniques](#psychological-techniques) + +[Key Terminologies](#key-terminologies) + +## Name of Game + +Below the Surface\_ + +## Genre + +Collaborative Puzzle Platformer\_ + +## Art Style + +Pixel Art\_ + +## How the Game Works + +The game works by traversing the level and solving complex puzzles with pipes and valves to advance +to the next level. However, there are enemies roaming around the level that will try and kill you, +there will be two types of enemies, one being your usual enemy, and the other a boss, which you will +need to kill if you’re to progress further in the game, you can avoid the enemies if you can, but +you have to defeat the bosses. Additionally, there might be toxic chemicals throughout the levels +that you’ll need to clear by completing the level, and there might be areas within the level that +are blocked by water in which you need to fix by placing a pipe on it or turning a valve. + +## How the Game is Played with Duos + +This game is mainly played by two people. One player will be pink, and the other will be blue. Their +colours are important as there will be interactable pipes around each level that will be +interactable to their specific player. If player pink attempts to interact with a blue pipe, they +cannot do so, it must be player blue that needs to interact with it. This should allow collaboration +between the two as they can’t advance if they don’t work together as a team. + +## How the Game is Played with Solo + +If the game is played solo. Then the colour of the player will be purple (mix of pink and blue). And +because it is purple, all the interactable pipes will also be purple. However, some levels may need +to remove or changed due to some levels requiring a duo to advance, but it should still challenge +the player overall. + +## How the Game is Won + +The game is won by defeating all the bosses in the game without running out of lives. You start with +3 lives. + +### The Player's Movement and Abilities Include + +- Walking +- Jumping +- Crouching +- Wrench Attack +- Falling Down +- Victory Dance +- Pick Up Pipe + +## Level Plan + +**Level 1**: Each player must complete their own tasks to get to the door. **Level 2**: Work as a +team to solve the puzzle (purple/solo player skips this level). **Level 3**: Puzzle is harder. +**Level 4**: Enemies start spawning on the right side of the screen. **Level 5**: Enemies are all +around the level avoid them and get to the boss checkpoint. **BOSS FIGHT!** (can only try 3 times or +however many lives collected from the checkpoint,  if YOU LOSE: start again/play again? YES: restart +**NO: Roll credits  IF WON**: proceed to explore the bunker.  **Level 6**: blob monsters are +introduced  (a short convo between players):  _"What is that?!"_ + +\_"Looks like matters are worse than we thought, there is a barrel of toxic waste knocked over and +contaminating the water!” + +\_“No wonder those rats were so big! But I was talking about that weird blob thing!” + +_"We'd better be careful and redirect those pipes quickly! let's go!"  / “I’d better redirect those +pipes carefully.”_ + +## How the Game is Lost + +The game is lost by being defeated by enemies or bosses. The player will have 3 hearts, but it can +be regenerated by picking up health items spread across the level. + +## Lore + +## The mission   + +Flooding was a thing of the past. The City of Thoth, a futuristic haven and a city filled with +gifted talents, had found a way to ensure that stormwater and sewage would never create problems on +the surface. However, due to an unknown phenomenon, the pipes below the surface have either been +broken or have gone missing. This has caused serious flooding above the surface which will put the +residents of the city in great danger. Your mission is to find, fix, and rearrange pipes to find the +root of this mess. + +### The Enemies   + +#### Normal Enemies   + +As you delve deep within the system you find rats, roaches, snakes, etc. which are common. The only +difference is that they have grown unnaturally larger, as their genes have been mutated via toxic +waste. They become aggressive and will attack you on sight. You will either defeat or avoid them. + +#### Boss Enemies   + +Toxic substances have always been a problem found in sewage sludge. But because they drink from it +quite often, they have become a danger to society, destroying pipes, causing blockages, which caused +the flooding in the first place. They must be defeated. + +#### The Reason   + +Scientists of Thoth have created a substance that has now powered the entire globe in the most +efficient way possible, in just over a year, the quality of life for millions of people has improved +by an unimaginable amount. But little did the world know that the chemical waste that these +substances would create, would spawn unimaginable creatures below the surface. The Scientists of +Thoth have gained the respect of millions and are on par with some of the most famous scientists in +the world such as Einstein himself. But fame blinded them, and they ignored the warnings, and now +they are met with a dangerous flood. + +#### Why You Are Down There   + +The Water Company have assigned one/two of their best workers to fix the problem as the others did +not make it back and even made the situation worse. The company is unsure as to why their system +failed but that is your job, to fix and to figure out what caused this mess as soon as possible. + +## The Water Company   + +Not much is known about the water company, they don’t serve any customers. However, they do whatever +it takes to fix any problems that may happen in any sewage system. Public opinion calls them +useless, but little do they know that this company does what it does to ensure the safety of people +through “unknown practices” as said by some reporters, but no one believes them. The Water Company +is labelled a mystery to most. + +## Your Tools   + +You and your partner get sent down the system with new tools. However, these aren’t ordinary tools, +they appear to be better in every way, but you weren’t told why your tools were replaced, only your +mission. + +## Did You Know? (Loading Screen Messages)   + +- The Water Company built the sewer system to effectively get rid of flooding once and for all… or + so we thought. +- Scientists of Thoth are regarded as geniuses, on par with Einstein. +- Your tools aren’t as ordinary as you think they are. +- Your boots and gloves help protect you from infection and injury, but they are not strong enough + to protect you from toxic waste or enemies! +- You must enter a door to reach the next level. + +## Reference Art / Early Sketches + +## Sewer Reference Art + +![image](images/SewerReferenceArt.png) + +## Water Reference Art + +![Image](images/WaterReferenceArt.png) + +## Pipes Early Sketch + +![images](images/EarlyPipes.png) + +## Created Assets + +![image](images/CreatedAssets.png) + +## Appendices + +### Defining the Game: The Victory and Loss Conditions + +| Victory Conditions | Loss Conditions | +| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | +| Minor victories include players completing a level and proceeding the next one as well as avoiding or defeating enemies. | Unable to solve the level in time | +| Major victories include players defeating a boss. | Killed in action by enemies | +| Final victory is achieved when players have successfully defeated all the main bosses and completed the game. | | + +### Active Challenges of the Game + +| Challenge Goal | What the Player Does | What is Shown to the Player | What Validates Player Action | +| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| Rotate, Move, Interact with Pipes to Progress Solving the Puzzle | Using arrow keys to navigate around the area, E to pick up the pipe, R to rotate it, E to place or drop, and E to interact with pipes with valves. | If single player, then the character will be purple and the pipes that they can interact with will show purple. If played with another player, then both characters will have their own colour and their own pipes like their colour that they can interact with. | Water that blocks the area will clear up, allowing the player to progress to the next level or complete one part of the puzzle. | +| Completing main puzzles under the time limit | The player must use their intuition to figure out the solution to the puzzle. | The player will be shown the time remaining and the progress of the puzzle | For every part of the puzzle that is completed the timer will be reset by 10 seconds or more depending on the difficulty of the puzzle. | + +### Internal Economy of the Game + +| Tangible Resources | What Value does it have? | How is it Exchanged in the Game? | Negative Feedback Mechanism (Avoid Rapid Growth) | Positive Feedback Mechanism (Avoid Stalemate) | Random Elements | +| ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------- | +| Powerups | Powerups aid the player as they must deal with enemies and the timer to complete the level. | For every enemy that is killed, there is a chance that a powerup may drop this may be a Repellent Power Up where once used, enemies will flee from you for a certain amount of time. | Game assigns more difficult opponent making it harder for the player to acquire a power up. | A better powerup may be given after defeating an enemy. | May potentially get a useless powerup. | + +| Intangible Resources | What Value does it have? | How is it Exchanged in the Game? | Negative Feedback Mechanism (Avoid Rapid Growth) | Positive Feedback Mechanism (Avoid Stalemate) | Random Elements | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| Health Bar | Defeating an enemy gives a chance to spawn a health item due to health that will be lost if the enemy hits the player. | For every hit of the enemy to the player, the player’s health goes down by one. | If your health is very low after defeating an enemy, there is a higher chance that they will drop a health item. | If you defeat the enemy without getting hit, you may have a chance to acquire a powerup | As the game progresses, there may be more than one opponent that spawn or a boss. | + +## Describing the Rules of the Game + +### Operational Rules (Intrinsic Relationship with Constitutive Rules) + +| Name | Description | Global or Local Rule | Impacts On | Relates to Constitutive | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------- | ----------------------- | +| Moving Pipes | The player must move or remove the pipes from or to their place. If not, they will not advance to the next level or will result in game over | Global | Current Game Being Played | Creating Pathway | + +### Constitutive Rules (Intrinsic Relationship with Operational) + +| Name | Global or Local Rule | Detail (How it is Implemented) | Relates to Operational | +| ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| Creating Pathway | Global | Each pathway available to the player may or may not be blocked by an obstacle, this will challenge the player into manipulating pipes in a way that will unblock those obstacles for the player to advance. | Moving Pipes | + +### Implicit Rules   + +| Name | Description | Impacts on... | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| Teamwork (for duo play only) | You should always work alongside your teammate to advance to the next level. Otherwise, the level will be too difficult to complete or even impossible. | Current game being played and game development | + +### Description of Game Mechanics using Rules + +Must move pipes (of the same colour as the player’s uniform) and turn valve wheels to redirect or +control waterflow/path blocking obstacles Enemies can be defeated by being jumped on or hit with a +wrench, ladders can be used to move up and down the play area. If all lives(hearts) are lost and no +checkpoint is reached return to the first level. Otherwise restart at checkpoint with 3 hearts. + +### Goals + +1. Player must complete the level +2. Player must defeat the boss +3. Player must solve the puzzle +4. Can Collect items/lives +5. When playing 2-player: players must work together! + +### Psychological Techniques + +| Goal (from previous step) | Psychological strategy | How the game design employs  this mechanism | How this game design using this mechanism achieves the goal. | +| ------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Players must complete the level | Classical Conditioning | To advanced to the next level the players must complete the level ahead of you, by solving the puzzles laid out within the level. | The players will associate a specific pipe to a missing piece within the pipes that they must connect to advance. | +| Players must defeat the boss | Operant Conditioning | To gain a big reward and advance to the next level, the players must defeat the boss, by not doing so you will lose. | The players will associate the boss as a threat. Therefore, giving the player a chance to defeat that threat to gain a bigger bonus, or lose if they get defeated. | +| Players must solve the puzzle | Flow Theory | As the players solve more and more puzzles the confident, they’ll become at solving them. This allows them to get into “the zone” which is the main meaning behind flow theory. | The players will associate each completed puzzle as an achievement, and with that, allows them to find a positive balance between challenge and skill. | +| Collect Items/Lives | Classical Conditioning | To keep playing longer, the players must collect lives and items. | The players will associate lives and items as aid to the game, which means they’ll have to obtain it to maximise their fun. | +| Players must work together | Bartle's Character Theory | This game (when played in duos) will allow the players to socialise and apply role-playing which allows them to build a relationship with one another. | The players will associate their partner as a need to complete to complete the game together. | + +## Key Terminologies + +**Operational Rules**: Those that directly guide behaviour concerning being able to complete a level +of the game. + +**Constitutive Rules**: Those that have a creative function, such as moving pipes to clear a +pathway. + +**Implicit Rules**: Unwritten/unspoken rules that are agreed upon by the game developers, such as +pink player can only move/operate pink pipes, blue player can only move/operate blue pipes and both +can operate purple, purple player can operate all pipes as they are a solo player. + +**Tangible Resources**: Something the player can touch/interact with. + +**Intangible Resources**: Something with no physical properties such as the health bar. + +**Classical Conditioning**: Relates to a behaviour in regard to a biological response. Animals and +humans can be easily controlled under classical conditioning principles. This is not often a +voluntary process, it’s about the provision of stimulus and the expected response. + +**Operant Conditioning**: Relates to the observation of behaviour responses. Related to classical +conditioning, we observe the player within the surrounding environment for maximum gain or +punishment. + +**Flow Theory**: Flow is when there’s a positive balance between challenge and skill in a game that +an ‘optimal challenge’ of activity is achieved. Also described as “being in the zone”. + +**Bartle’s Character Theory**: Relates to how players think of their characters in video games, and +how they should engage with others or how they enact their characters. What role the character plays +in relation to the game. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM11April.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM11April.md new file mode 100644 index 00000000..58639014 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM11April.md @@ -0,0 +1,70 @@ +# Meeting minutes + +Monday at 4:40 11/04/2022 + +Attendees: Lily Lan, Nick Agiazis, Anthony George, Sarah Gosling, Riley Nicholas Dellios, Morgaine +Barter, Bella Chhour (joined at 5:10) + +Absent: Huy Pham + +Next meeting: 14/4/2022 6PM Thursday + +Minutes by: Morgaine Barter and Anthony George + +## Agenda + +Not specified + +Note: at 5PM we split into project groups on separate Teams channels. + +## Announcements + +Please start working on Task 6.x. + +For Task 6.2, this is an update of the company report and project submissions to be added by the +21st to allow time to compile. More information will be coming but: + +This will be worked on collaboratively on GitHub by submitting `.md` PRs to team folder in branch: +task6.2/company-report-project-updates + +This will include discussion on testing and data strategies and Software Requirement Specification +documents, along with a project update + +## Discussion + +### Build a cool game + +- running through turning things into markdown files and creating PR’s. +- Installing vs code extensions +- And going through the version control video workshop in unit resources to help make sure we’re not + doubling up when going to record a reference video (hopefully tomorrow) + +### Arcade Machine + +- Viewed Anthony’s presentation, displaying a mock-up of the user interface. +- Discussed the pros-cons of game layouts, carousel layout may require uses to perform a lot of + actions to find their game. +- Discussion on including text to indicate next and prev game +- Sarah suggested the carousel be an Eternal Carousel with + - Option to change background image + - Option to change background music + - Option to change selector sound + - Option to change game menu view + - Option to disable animations () +- Arcade machine will need a ‘Start’ button to exit a game when playing? (Alternatively, player uses + ESC to escape) +- Quickly discussing which class would be responsible for drawing the assets, button class or grid + layout class +- Drawing items off the screen with the grid layout class? - solution suggestion was to use a + negative constant to reference off left of screen. +- Mouse pointer can be used, joystick can emulate it? + +## Action Items + +- [ ] Everyone: Documents (md) needed for GitHub: testing plan/requirements, data requirements, + Software Requirements, + [Epic template](https://github.com/thoth-tech/handbook/blob/main/docs/leadership/epic-template.md) +- [ ] Everyone: Project report - (power point slides) updates with user stories, and as mentioned + documents as slides. +- [ ] Everyone: Trello board clean up +- [ ] Everyone: Retrospective: Miro (update) at https://miro.com/app/board/uXjVOBrtXD4=/ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM14April.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM14April.md new file mode 100644 index 00000000..7fdbf6d8 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM14April.md @@ -0,0 +1,70 @@ +# Meeting minutes + +Monday at 4:40 14/04/2022 + +Attendees: Nick Agiazis, Anthony George, Sarah Gosling, Riley Nicholas Dellios, Morgaine Barter, +Bella Chhour, Lily Lan, Huy Pham + +- [ ] Next meeting: 21/4/2022 6PM Thursday + +Minutes by: Morgaine Barter + +## Agenda + +by Nick Agiazis + +- create a folder within Thoth Tech documentation/docs/SplashKit/Applications called meeting minutes +- start documentation conversion to MD files for GitHub uploads, starting with meeting minutes. +- send Software Requirements Draft Doc to Glory Lee for feedback TODAY (before the public holiday + and break) - Done +- work on group retrospective (Miro board) + +## Announcements + +[14/04/2022 11:41 am] TALIA ZIDAR Important! + +### Have you finished the design stage? + +Hi General, + +I know I said that you should start working on development this week, but first please double check +you are ready. It is important that everyone on the team is on board, ready, and the plan is +correct. Ideally you should go through this checklist with EVERY new task you start (that's how you +work in Agile) + +Here is a checklist to double check your team is ready: + +- What is the goal of the team (epic)? +- Have you identified User Stories (around 5+)? Put them in Trello or in GitHub documentation repo +- Have you completed the Software Requirements Specification documents (the information will come + out of the user stories) This is needed for 6.2 task +- Have you filled the backlog based on the SRS? +- Is this backlog related to the goal? +- Are all your members aligned across the whole team and product lead? +- Does your plan align with the goal? +- Remember documentation is a deliverable in itself. + +## Discussion + +- SRS draft completion +- User stories uploaded to Trello +- Testing Strategies + - one for each arcade machine and build a game (software and hardware) +- GitHub - MD files need to convert meeting minutes + - and other important documents once approved + +### Build a cool game + +- Next meet on Tuesday at 6PM to discuss testing strategies +- and how we are going to record them + +### Arcade Machine + +- Hardware requirement Planning + +## Action Items + +- [ ] Everyone: SRS file, draft complete and sent for feedback +- [ ] Everyone: Update trello +- [ ] Everyone: Start file conversion to GitHub (docs to md files) +- [ ] Everyone: Retrospective (only covered briefly at the end as we ran out of time) diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_22ndAugust.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_22ndAugust.md new file mode 100644 index 00000000..cdfa1368 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_22ndAugust.md @@ -0,0 +1,65 @@ +## Meeting minutes - Build an Exceptional Game  + +### Monday: 22/08/2022  + +Attendees at 5:00pm: Morgaine Barter, Lachlan Morgan, Daniel Agbay, Lily Lan + +Absent: Jiahao Zheng, Roy Chen, Robert Osborne + +Next meeting: 25/8/2022  1pm Thursday (On campus, building T) + +Minutes by: Morgaine Barter + +Agenda: Morgaine Barter + +- Outline level creation process +- Keep checking Trello and updating task status/progress + +Announcements: + +Panel presentations this week - career hacking event posted in general + +Discussion: + +Level building guidelines + +To build water elements: + +1. Place an empty hold/turn/multi turn pipe down + +2. Place a holdpipe/turnpipe/multiturnpipe down that is the same as the empty pipe + +3. Place the water over/under it on another layer (ex: empty pipe on layer 1, water on the same + tile on layer 2) + +- Use regular pipes to connect it all together + +To build a level: + +4. Place blue and pink players on layer 1 + +5. Place the door on layer 1 + +6. Use half blocks for decoration or test if they can be used, but have alternatives + +7. Make sure ladders are all on the same layer! + +8. Only use half blocks and diagonal blocks decoratively + +9. Make sure to have the latest build of both the game and the level editor + +Please read before creating a +level: [https://github.com/thoth-tech/build-a-game-team/tree/main/documentation](https://github.com/thoth-tech/build-a-game-team/tree/main/documentation) + +And : [https://github.com/lmorg42/level-design](https://github.com/lmorg42/level-design) + +For instructions on how to operate the level editor. + +! Please MAKE SURE you have the most recent level editor before creating levels ! + +Action Items: General/Everyone: + +- Everyone should create at least one level +- Test them before uploading + +- Implement to play in the game with appropriate names for each level diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_25thJuly.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_25thJuly.md new file mode 100644 index 00000000..10373d06 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_25thJuly.md @@ -0,0 +1,70 @@ +## Meeting Minutes - Build an Exceptional Game + +### Monday: 25/07/2022 + +Attendees at 5:00PM: Morgaine Barter, Lily Lan, Lachlan Morgan, Daniel Agbay, Roy Chen, Jiahao +Zheng, Robert Osborne + +Next meeting: 28/7/2022 1:30pm Thursday on campus (Building T)\* + +Minutes by: Morgaine Barter + +Agenda: Morgaine Barter + +1. ask what year teammates did intro to programming + +2. ask if teammates have done object-oriented programming and when + +3. Do we have any GitHub experts in our team? + +4. ask if team has any experience making games in other units or for work + +5. ask if anyone has comfortability creating a character or visual assets for the game + +6. (as I would like to at least get a list of the visual assets we require for our game of choice, + choose a colour story/theme) and add this information to the design doc for planning + +7. set another meeting for thursday to continue brainstorming + +8. make sure 5pm Monday is the best time for B.A.E.G team for stand-up meet + +9. There have been edits made to our repo inside meeting minutes, these requests for fixes must be + dealt with before we start uploading this terms meeting minutes. + +Announcements: + +Discussion: + +| Name | Intro to Programming | OOP | game making experience | +| --------------- | -------------------- | -------------------- | ----------------------- | +| Morgaine Barter | 2018 | 2022 (currently) yes | basic | +| Lily Lan | +| Lachlan Morgan | 2018 | 2019 | only from last semester | +| Daniel Agbay | +| Roy Chen | 2020 | 2022 (currently) | no | +| Jiahao Zheng | 2019 | 2022 (currently) yes | basic | +| Robert Osborne | 2020 | 2021 yes | game design 2021 | + +Comfortable making visual assets: + +Morgaine Barter - yes (I love doing this but don’t want to JUST do this) Lily Lan - yes Lachlan +Morgan - is working on his own game as well so does not need to contribute visual assets Daniel +Agbay - yes Roy Chen yes Jiahao Zheng making the game logo Robert Osborne no (is making our sound +assets) + +Build an exceptional game: + +Monday 5pm + +Arcade Machine: + +Monday 5pm + +Action Items: General/Everyone: + +Collect information on people's experience and skills + +Fix T1 GitHub recommended processes (there was a lint error in sound effect uploads and a +txt/prettier error in minutes... which I am surprised about) + +Work on design document making decisions as we go to form our game concept and design. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_30thJuly.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_30thJuly.md new file mode 100644 index 00000000..ee35680d --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_30thJuly.md @@ -0,0 +1,55 @@ +## Meeting Minutes - Build an Exceptional Game + +### Saturday: 30/07/2022 + +Attendees at 2:00PM: Morgaine Barter, Lily Lan, Lachlan Morgan, Daniel Agbay, Roy Chen, Jiahao +Zheng, Robert Osborne + +Next meeting: 1/8/2022 4:30-5:30pm Monday\* & Thursday on campus building T 1:00-3pm + +Minutes by: Morgaine Barter + +Agenda: Morgaine Barter + +1. Trello decisions + +2. design document clean up + +3. ask if anyone has comfortability creating a character or visual assets for the game + +4. create a list of the visual assets we require for our game of choice, and add this information + to the design doc for planning + +5. set another meeting for thursday to continue brainstorming + +6. make sure 5pm Monday is the best time for B.A.E.G team for stand-up meet + +Announcements: + +Discussion: + +| Name | Intro to Programming | OOP | game making experience | +| --------------- | -------------------- | -------------------- | ------------------------ | +| Morgaine Barter | 2018 | 2022 (currently) yes | basic | +| Lily Lan | 2020 | 2021 | only last trimester | +| Lachlan Morgan | 2018 | 2019 | only from last semester | +| Daniel Agbay | 2020 | 2021 | yes game design and more | +| Roy Chen | 2020 | 2022 (currently) | no | +| Jiahao Zheng | 2019 | 2022 (currently) yes | basic | +| Robert Osborne | 2020 | 2021 yes | game design 2021 | + +Comfortable making visual assets: + +Morgaine Barter - yes (I love doing this but don’t want to JUST do this) Lily Lan - yes Lachlan +Morgan - is working on his own game as well so does not need to contribute visual assets Daniel +Agbay - yes Roy Chen yes Jiahao Zheng making the game logo Robert Osborne no (is making our sound +assets) + +Action Items: General/Everyone: + +Collect information on people's experience and skills + +Fix T1 GitHub recommended processes (there was a lint error in sound effect uploads and a +txt/prettier error in minutes) + +Work on design document making decisions as we go to form our game concept and design. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_3rdSeptember.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_3rdSeptember.md new file mode 100644 index 00000000..46fbbea2 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_3rdSeptember.md @@ -0,0 +1,47 @@ +## Meeting minutes - Build an Exceptional Game  + +### Saturday: 3/09/2022  + +Attendees at 2:00pm: Morgaine Barter, Lily Lan, Lachlan Morgan, Daniel Agbay, Roy Chen, Jiahao +Zheng, Robert Osborne + +Next meeting: 8/9/2022 1:30pm Thursday\* On campus + +Minutes by: Morgaine Barter + +Agenda: Morgaine Barter + +1. Make levels + +2. Assign new tasks and update current Trello cards + +3. Discuss progress of current ongoing tasks. + +Announcements: + +Start Ontrack tasks for this week + +- We need more levels! And we need to order these levels appropriately. (on Thursday) + +Discussion: + +Level editor can now load working progress of levels via the following command:  (this example is +for 1 layer USING the level editor) + +./test -load 1 file0.txt  reallocation of player keys (swapped needs to be done in the next 2 +weeks) player 1: AWSD movement action buttons: R, T,  Y, F, G, H + +Player 2: <- ^ -> arrow movements action buttons: U, I, O, J, K, L + +Listened to demo of long music loop. (still in progress, very cool) + +Action Items: General/Everyone: + +- Making levels before Thursday (everyone must make at least 1 functioning level!) +- Death sequence for enemies needs to be implemented in the next week + +- finish creating the boss animation! (Morgaine) +- Sound effect for player being hit by enemy “ouch” (Lily) and continue working on HUD +- Working on large level music (Robert) +- Company intro screen (Roy) +- Background story (lore) shown from main menu button (Jiahao) using design doc lore. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_4thAugust.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_4thAugust.md new file mode 100644 index 00000000..2cd4d687 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_4thAugust.md @@ -0,0 +1,42 @@ +## Meeting minutes - Build an Exceptional Game  + +### Thursday: 4/08/2022  + +Attendees at 5:00pm: Morgaine Barter, Lily Lan, Lachlan Morgan, Daniel Agbay, Roy Chen, Jiahao +Zheng, Robert Osborne + +Next meeting: 6/8/2022 2pm Saturday\* + +Minutes by: Robert Osborne + +Agenda: Morgaine Barter + +1. Design first levels + +2. Potential level editor + +Announcements: + +(no announcements this week) + +Discussion: + +Logistics of different pipes and obstacles so that levels made sense + +Spoke with Andrew Cain about creating a level editor (Discussed further between Lachlan and Robert) + +Got to know each other a bit better and our experiences relevant to game creation + +Action Items: + +-level editor + +-game doc finished off + +General/Everyone: + +- Complete assigned Trello tasks (good contribution evidence) and upload files to both the Trello + board and GitHub please! + +- If you have not as-yet contributed to coding, make sure you have been assigned to a task +- If you have finished a task please move it to the correct done column and pick another task! diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_6thAugust.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_6thAugust.md new file mode 100644 index 00000000..4b0fd0d2 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_6thAugust.md @@ -0,0 +1,59 @@ +## Meeting minutes - Build an Exceptional Game  + +### Saturday: 6/08/2022  + +Attendees at 5:00pm\*: Morgaine Barter, Lachlan Morgan, Daniel Agbay, Robert Osborne Absent: Roy +Chen, Jiahao Zheng, Lily Lan + +Next meeting: Monday 8/08/2022 4:30-5:30 & Thursday 6:15pm + +Minutes by: Morgaine Barter + +Agenda: Morgaine Barter  \*(either posted or discussed on Trello) + +- To make sure everyone has made contributions to GitHub +- explaining the programming contribution plan/workflow +- to get any feedback on contributions prior to uploading to GitHub +- how to make meeting minutes (quick rundown) +- set next week's meeting - do we want to have a retrospective meeting on Monday 4:30-5:30? yes + +Announcements: Check unit channel general for these\* + +Important! + +Week 4 Tasks + +SIT378-SIT782 Team Project (B) - Execution And Delivery 2022 T2 + +Hi Everyone, + +This is a reminder that the tasks must be submitted by Sunday, 7 August. + +- Task 4.1P: Aiming for Pass +- Tasks 4.1P and 4.2C: Aiming for Credit +- Tasks 4.1P, 4.2C, and 4.3D: Aiming for Distinction +- Tasks 4.1P, 4.2C, 4.3D, and 4.4HD: Aiming for High Distinction + +It is required that two documents be submitted via Ontrack for tasks 4.1P, 4.2C, and 4.3D: + +1. Individual retrospective/progress report, + +2. Evidence. + +In the task 4.4HD, the slides for a presentation of three minutes must be submitted. + +Discussion: + +- discussed level editor and its functionality: when modified and tested between 64x64 cells, 32x32 + cells and 16x16 cells 32x32 was found the most appropriate tile size. + +- Camera scroll has been added by Robert +- More pipes have been added to the level editor by Daniel +- Logo has been uploaded by Jiahao +- Game music is being worked on by Robert and demo was added to channel + +Action Items: General/Everyone: + +Complete 4.x Ontrack tasks by this Sunday update worklog hours! + +Upload contributions to GitHub (such as completed image assets for enemies, logo, etc.) diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_8thAugust.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_8thAugust.md new file mode 100644 index 00000000..c0dfb90d --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_8thAugust.md @@ -0,0 +1,130 @@ +## Meeting minutes - Build an Exceptional Game  + +### Monday: 8/08/2022   + +Attendees at 4:30pm: Morgaine Barter, Lily Lan, Lachlan Morgan, Daniel Agbay,  Jiahao Zheng, Robert +Osborne + +Absent: Roy Chen + +Next meeting: \*Thursday 6:15pm + +Minutes by: \*everyone? + +Agenda: by Morgaine Barter posted in Calander invite + +- Retrospective meeting covering the points in announcements + +Announcements: + +6/08 12:21 pm ANTHONY GEORGE + +5.1P + +Making Progress + +Hey Thoth-Tech Leadership, we will need to submit our progress task report next weekend, so let's +use some time this week to document where everyone is at with their projects, specifically: + +- Add descriptions of progress to each project + +- Include a forecast of the likely state for each project at the end of the trimester +- Indicate any changes to plans for the project. +- Add any new projects that have started since 2.3P was created + +According to the task sheet, the updates should be brief and high level – providing a summary not a +detailed description. This submission serves as a check point, indicating how things are progressing +at the midpoint in the trimester. + +Ideally, this report should be a markdown document in the company’s central documentation git +repository. In this way, people can contribute to this in a way that is easy to evidence for +inclusion in their portfolios. + +I added task 2.3P to the repo, but has it been merged? In hindsight, it should probably be broken +into four, (each of the products). + +Is this something operations/processes/documentation can take care of?  Then it's just a matter of, +each team lead can then update their section and do a pull request for it to be included in the +final submission. + +Discussion: + +Add descriptions of progress to each project + +Description of project: building arcade game/s for 2 player arcade machines for the intended use of +showcasing SplashKit functionality and current students work to future students during Deakin open +days + +Testing on laptops until physical machines are built. + +The completed games are uploaded to the Arcade-games repository and are grabbed from the +Arcade-machine to play at run time. This allows the machine to display a library of games We will +have our game at an enjoyably playable state before uploading to the arcade games repo.  The +main-focus is the group project, smaller/solo projects are being used to test SplashKit functions +before working on or implementing into the group project as upskilling resources and if they reach +an appropriate level of completion, they will be to upload to the arcade-games repo + +this requires: -  a thumbnail for game selection of 600x540pixels - a welcome screen (with game +title and student name/creator) - a no toggle function to remove border around game with x - an esc +quit option (while !quit requested) - a max window size of 1600 x 900 for game + +_Include a forecast of the likely state for each project at the end of the trimester_ + +Below the Surface: (group game: main focus) + +A 2D Puzzle Platformer that will be built using Splashkit’s functionalities, inspired by a few +classical arcade games. And should be playable by the end of this trimester using the arcade +machine. + +Forecast: + +- first level finished by 22/08/22 with music + +- Collectable items such as hearts will be added to the player lives  double lives will double + players lives. +- Many levels can be made easily now, level change yet to be implemented(after level one is awesome) +- One player will be playable before the end of trimester +- Two player will need to be refined + +Fight game(placeholder): Lachlan Morgan + +Street fighter made in splashkit (started last trimester) + +Already uploaded to arcade-games repo, is still being polished when possible. + +Maze Walker(placeholder): Robert Osborne + +A 2.5D maze walking game, will be a raycasting engine built using SplashKit, something similar to +Wolfenstein 3D, being used as a way to upskill in the usage of SplashKit and can have a playable +prototype done by the end of the trimester. Will be able to played on the arcade machine by then as +well. Will only be one player.  Will hopefully have at least 2 prototype levels by the end of the +trimester. + +\* + +Colour Wrong: Lily Lan + +Game design created last trimester: a platform game that the player is a ball and they can only +touch platforms of the same colour as themselves, player can change colours to make it through +different platforms. - again used for upskilling and as an optional task + +Indicate any changes to plans for the project. + +- how to doc has been replaced by Trello + +Add any new projects that have started since 2.3P was created + +Level editor: [https://github.com/lmorg42/level-design](https://github.com/lmorg42/level-design) + +The level editor has been made so that new levels can be made very quickly + +The editor started off just placing tile blocks, now it places tiles and pipes in layers (you can +place pipes on top of tiles) the editor exports a text file when key A is pressed with tile/pipe +information + +You can also scroll the camera by holding the alt key to reach areas of the level beyond the window +size + +Action Items: General/Everyone: + +Create MD file of the discussion section for 5.1 submission collaboration. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_8thSeptember.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_8thSeptember.md new file mode 100644 index 00000000..65da7628 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/MM_GameTeam_8thSeptember.md @@ -0,0 +1,58 @@ +## Meeting minutes - Build an Exceptional Game  + +### Thursday: 08/09/2022  + +Attendees at 1:00pm: Morgaine Barter, Lily Lan, Lachlan Morgan, Robert Osborne + +absent: Renhao Chen, Jiahao Zheng and Daniel Agbay + +Next meeting: 12/09/2022 2pm Monday for InnoFes reps\* + +Minutes by: Morgaine Barter and Robert Osborne + +Agenda: Morgaine Barter + +- decide the order of levels, and ensure everyone has made at least one. + +- Share the progress of other tasks + +Announcements: + +- speech night and pizza 6pm Friday for InnoFes 16/09/2022 (building T) + +(please sign up and indicate dietary requirements if you have any so they know how much pizza to +order) + +- task sheets are now updated for Ontrack, so please make a start on the next lot of tasks soon. + +Discussion: + +- tested different levels + +- looked at Roberts's work on his 2d 3d game used for upskilling and future trimesters game. + +- listened to how the hurt sound Lily implemented sounds in the game. + +Level order so far: ' + +1. level 0 (levels folder) + +2. 1-4 txt (in main folder) + +3. easy + +4. level3 + +5. level6 + +6. surf + +7. 4c (Four trials of thoth) + +8. combat level + +Bonus level too many roaches (where to put this in as a hidden level?) + +Action Items: General/Everyone: + +- finish up design tasks as quickly as possible so their implementation can begin diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background2.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background2.png new file mode 100644 index 00000000..0a12c30a Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background2.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background3.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background3.png new file mode 100644 index 00000000..533fcc23 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background3.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background4.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background4.png new file mode 100644 index 00000000..ea93d098 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Background4.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Blob.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Blob.png new file mode 100644 index 00000000..c72420dc Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Blob.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/BlueGuy.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/BlueGuy.png new file mode 100644 index 00000000..328f501f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/BlueGuy.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/CreatedAssets.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/CreatedAssets.png new file mode 100644 index 00000000..e172b5be Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/CreatedAssets.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Door.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Door.png new file mode 100644 index 00000000..04480c0f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Door.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/EarlyPipes.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/EarlyPipes.png new file mode 100644 index 00000000..d32d1c61 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/EarlyPipes.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/LivesHealthIcon.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/LivesHealthIcon.png new file mode 100644 index 00000000..5a27d1eb Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/LivesHealthIcon.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Logo.png.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Logo.png.png new file mode 100644 index 00000000..ca2906fb Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Logo.png.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/MENUBackgroundDark.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/MENUBackgroundDark.png new file mode 100644 index 00000000..4707b266 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/MENUBackgroundDark.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Pasted image 20220925150818.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Pasted image 20220925150818.png new file mode 100644 index 00000000..3f8f4852 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Pasted image 20220925150818.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/PinkGirl.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/PinkGirl.png new file mode 100644 index 00000000..04193f2d Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/PinkGirl.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Pipes.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Pipes.png new file mode 100644 index 00000000..c2ad7e25 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Pipes.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/PurpleGuy.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/PurpleGuy.png new file mode 100644 index 00000000..c44b0d36 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/PurpleGuy.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Rat.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Rat.png new file mode 100644 index 00000000..15eb8e3f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Rat.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Roach.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Roach.png new file mode 100644 index 00000000..a3d2ce5e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/Roach.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/SewerReferenceArt.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/SewerReferenceArt.png new file mode 100644 index 00000000..8b502ded Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/SewerReferenceArt.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/WaterReferenceArt.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/WaterReferenceArt.png new file mode 100644 index 00000000..d9d43aaa Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/WaterReferenceArt.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/blue.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/blue.png new file mode 100644 index 00000000..758c9a12 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/blue.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bluecap.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bluecap.png new file mode 100644 index 00000000..4dc7994f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bluecap.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/blueehb.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/blueehb.png new file mode 100644 index 00000000..526f9114 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/blueehb.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bluehb.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bluehb.png new file mode 100644 index 00000000..b9c0c578 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bluehb.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bts_tiles.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bts_tiles.png new file mode 100644 index 00000000..abab2616 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/bts_tiles.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button.png new file mode 100644 index 00000000..39cc979e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button_sml.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button_sml.png new file mode 100644 index 00000000..1fbfc66f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button_sml.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button_sml_blk.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button_sml_blk.png new file mode 100644 index 00000000..82242f70 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/button_sml_blk.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/collectables.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/collectables.png new file mode 100644 index 00000000..2bdbafa4 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/collectables.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/companylogo1.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/companylogo1.png new file mode 100644 index 00000000..1117bae4 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/companylogo1.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/companylogo2.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/companylogo2.png new file mode 100644 index 00000000..a8963231 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/companylogo2.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/decorative_blocks.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/decorative_blocks.png new file mode 100644 index 00000000..54add65e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/decorative_blocks.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/decorative_misc_pipes.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/decorative_misc_pipes.png new file mode 100644 index 00000000..3c9adc99 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/decorative_misc_pipes.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/edge.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/edge.png new file mode 100644 index 00000000..8191448e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/edge.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/empty_block_le.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/empty_block_le.png new file mode 100644 index 00000000..022f86d9 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/empty_block_le.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/gameover.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/gameover.png new file mode 100644 index 00000000..52c2c8ed Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/gameover.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/half_blocks.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/half_blocks.png new file mode 100644 index 00000000..47b4fe6e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/half_blocks.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_misc_pipes.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_misc_pipes.png new file mode 100644 index 00000000..fca956f9 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_misc_pipes.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_misc_pipes_empty.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_misc_pipes_empty.png new file mode 100644 index 00000000..748f2811 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_misc_pipes_empty.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes.png new file mode 100644 index 00000000..b9c93ded Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes_empty_clear.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes_empty_clear.png new file mode 100644 index 00000000..bf55e81e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes_empty_clear.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes_empty_le.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes_empty_le.png new file mode 100644 index 00000000..9a2bf8cd Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/holdable_pipes_empty_le.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/ladder.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/ladder.png new file mode 100644 index 00000000..2e6a9f57 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/ladder.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/menubackground.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/menubackground.png new file mode 100644 index 00000000..3c4e15a5 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/menubackground.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/multipipes_empty.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/multipipes_empty.png new file mode 100644 index 00000000..66162ae5 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/multipipes_empty.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/multipipes_empty_clear.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/multipipes_empty_clear.png new file mode 100644 index 00000000..727d60a3 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/multipipes_empty_clear.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pink.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pink.png new file mode 100644 index 00000000..abbfe93f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pink.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkcap.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkcap.png new file mode 100644 index 00000000..9eb73aeb Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkcap.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkehb.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkehb.png new file mode 100644 index 00000000..02046aaa Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkehb.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkhb.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkhb.png new file mode 100644 index 00000000..5a284f5e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pinkhb.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pipes_64.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pipes_64.png new file mode 100644 index 00000000..d8e91f6e Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/pipes_64.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purplecap.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purplecap.png new file mode 100644 index 00000000..e7a87351 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purplecap.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purpleehb.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purpleehb.png new file mode 100644 index 00000000..7aeaff80 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purpleehb.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purplehb.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purplehb.png new file mode 100644 index 00000000..fda9e8f5 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/purplehb.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/readme.txt b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/readme.txt new file mode 100644 index 00000000..5d8bc906 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/readme.txt @@ -0,0 +1 @@ +Place images in this folder. SplashKit can work with png, jpeg, jpg, or tif files. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/slimesurfin.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/slimesurfin.png new file mode 100644 index 00000000..0cf25329 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/slimesurfin.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake.png new file mode 100644 index 00000000..42762bf3 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake10.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake10.png new file mode 100644 index 00000000..7ce3ee62 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake10.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake20.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake20.png new file mode 100644 index 00000000..fd246e09 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake20.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake30.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake30.png new file mode 100644 index 00000000..1b5a2435 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake30.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake50.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake50.png new file mode 100644 index 00000000..786de9be Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/snake50.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/solid_blocks.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/solid_blocks.png new file mode 100644 index 00000000..f778ea2f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/solid_blocks.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/teamlogo.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/teamlogo.png new file mode 100644 index 00000000..eb853c49 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/teamlogo.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/temp540.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/temp540.png new file mode 100644 index 00000000..d6404e84 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/temp540.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/title.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/title.png new file mode 100644 index 00000000..1810c3f1 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/title.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/toxic_blocks.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/toxic_blocks.png new file mode 100644 index 00000000..ae5a41d0 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/toxic_blocks.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes.png new file mode 100644 index 00000000..78539352 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes_empty.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes_empty.png new file mode 100644 index 00000000..8654d111 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes_empty.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes_empty_clear.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes_empty_clear.png new file mode 100644 index 00000000..04967d78 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/turn_pipes_empty_clear.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/waterRat.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/waterRat.png new file mode 100644 index 00000000..e8adfd17 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/waterRat.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/water_blocks.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/water_blocks.png new file mode 100644 index 00000000..cb7d210c Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/water_blocks.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/images/winscreen.png b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/winscreen.png new file mode 100644 index 00000000..48002df5 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Meeting Minutes/images/winscreen.png differ diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/index.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/index.md new file mode 100644 index 00000000..dafec857 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/index.md @@ -0,0 +1 @@ +This will have all meeting minutes inside for review. diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/mm17march.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm17march.md new file mode 100644 index 00000000..98fda3fb --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm17march.md @@ -0,0 +1,41 @@ +# Meeting Minutes + +Sunday 17/03/2022 (start time: 6pm – 7pm) + +Attendees: Lily Lan, Nick Agiazis, Anthony George, Sarah Gosling, Riley Nicholas Dellios, Morgaine +Barter, Huy Pham + +Minutes by: Morgaine Barter + +Next meeting: 21/03/2022 (After Unit Lecture) + +## Agenda + +- Worklog organized for Applications team in Teams files +- Research Compatibility of Raspberry Pi +- software deliverables - Making games for 'cool game team' - start +- where to upload files for version control – GitHub +- For things like new functions +- Game project file deliverables + +## Announcements + +- None specified + +## Discussion + +- common “cool” 2D Arcade Game types: +- Platform game where the player must climb to stay alive (like Mario or icy towers) +- Fighting game (either 2 players or 1 player vs CPU) +- Space game 2.0 +- pac-man style game (collecting items/survival) +- Momo's idea: conveyor belt factory with build missions. + +## Action items + +- [ ] Everyone: Complete 1.1P +- [ ] Everyone: Complete Onboarding process +- [ ] Nick: Create Applications Trello board Create +- [ ] Everyone: Join Application Trello board +- [ ] Everyone: Upload worklog hours from the first 2 weeks (required date format) +- [ ] Everyone: Start Upskilling on C++ / SplashKit understanding diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/mm4April.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm4April.md new file mode 100644 index 00000000..9447acf7 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm4April.md @@ -0,0 +1,38 @@ +# Meeting Minutes + +Monday 4/04/22 (start time: 6pm – 7pm) + +Attendees: Lily Lan, Nick Agiazis, Anthony George, Sarah Gosling, Riley Nicholas Dellios, Morgaine +Barter, Huy Pham + +Minutes by: Morgaine Barter + +Next meeting: 11/04/2022 (After Unit Lecture) + +## Agenda + +- Task discussion (OnTrack) +- Trello: used to keep track of task completion +- Feedback pending... (this week) + +## Announcements + +- None specified + +## Discussion + +- GitHub Repos: note: only put finished games in arcade game repo. +- Process for adding a game to the repo: +- Create a new repo to work on your new game development +- Branch and merge as usual within that repo until game is finished +- Create a new branch in arcade-games repo +- Clone of arcade-games repo +- Add game to your branch +- Push to remote +- Create pull request to merge to main + +## Action items + +- [ ] Everyone: In progress tasks: Documentation (continually working on all trimester) +- [ ] Riley: Git commit using vscode demo by Riley and cloning repositories to desktop (including + handbook to contribute to) diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/mm5May.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm5May.md new file mode 100644 index 00000000..094a34b2 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm5May.md @@ -0,0 +1,51 @@ +# Meeting minutes + +Thurday at 4:40 5/05/2022 + +Attendees: Nick Agiazis, Anthony George, Sarah Gosling, Riley Nicholas Dellios, Morgaine Barter, +Bella Chhour, Lily Lan, Huy Pham, Lachlan + +- [ ] Next meeting: 12/5/2022 6PM Thursday + +Minutes by: Morgaine Barter + +## Agenda + +- Documentation + - Spoke about where documenation currently is. + +## Announcements + +- New Team Member joining us + +## Discussion: + +- Documentation Chat +- Introducing the Agenda and Lachlan Morgan + +## Meeting + +- 6pm: introducing the Agenda and Lachlan Morgan + +- 6.30pm - Documentation Chat + +- 6:45pm: issue with input between arcade machine and game executables as both are looking for input + in update (need to run as admin to ignore input) not sure how to go about fixing this problem. + +- 7:05 different way to block input? Using delay? Mouse (if mouse leaves window...) + +## Action Items: + +- how to build documentation for ‘build a cool game’ + +- Testing strategies\* (expected input responses as well such as movement or actions) + +- Bug report template + + - (How to load games using config file) - user guide + +- Data collection strategy (work on next week as a user feedback metric) + +- Arcade test cases\*\* important + +By week 11 handover for next trimester diff --git a/src/content/docs/Splashkit/Applications/Meeting Minutes/mm7april.md b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm7april.md new file mode 100644 index 00000000..7c3532fb --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Meeting Minutes/mm7april.md @@ -0,0 +1,52 @@ +# Meeting Minutes + +Thursday 7/4/2022 (start time: 6pm – 7pm) + +Attendees: Lily Lan, Nick Agiazis, Anthony George, Sarah Gosling, Riley Nicholas Dellios, Morgaine +Barter, Huy Pham + +Minutes by: Morgaine Barter + +Next meeting: 14/04/2022 (After Unit Lecture) + +## Agenda + +- Collect Feedback on Showcase + +## Announcements + +- None specified + +## Discussion + +- Need a software requirements page in the presentation to explain +- How the games are made will be played on the physical machine +- (How many buttons, what types of buttons, what size of display) +- How is the integration going to work from laptop-arcade machine versions? +- Use the link below to plan this documentation: + https://www.perforce.com/blog/alm/how-write-software-requirements-specification-srs-document + “In the coming future, I look forward to your plan and design of implementation (the medium level + of description, not the low level coding details) based your listed goals/expected deliverables. + Please refer to the above indicated SRS reference Step 3. Detail the requirements. 4. Deliver it + for approval. And you will see all these would help achieving toward to the delivery plan and QA + processes.” + +Assign roles for team members: e.g.: + +- create an agenda and send it out to everyone (either by email or on teams with @’s for each member +- take meeting minutes and upload to teams' files + +## Action items + +- [ ] User stories: (need to make a few of these and should have been done already before we started + making things, part of the design and planning process) NEED to take meeting minutes to/and + IMPROVE COMMUNICATION within the team +- [ ] Meeting Agendas: for meetings so people can be prepared and to stay on topic +- [ ] Assign roles for team members: e.g.: + - [ ] create an agenda and send it out to everyone (either by email or on teams with @’s for each + member +- [ ] Take meeting minutes and upload to teams' files +- [ ] Everyone: must check the minutes and agendas, ask questions where clarification is needed. +- [ ] Need to investigate how to execute these files that use SplashKit on a physical arcade + machine. +- [ ] GitHub Document to be made: Showing the software requirements diff --git a/src/content/docs/Splashkit/Applications/Systems-Req.md b/src/content/docs/Splashkit/Applications/Systems-Req.md new file mode 100644 index 00000000..2fb9e8a0 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Systems-Req.md @@ -0,0 +1,174 @@ +## Software Requirements Specification 14/04/2022 + +Anthony George - 220180567 +Riley Dellios - 219191105 +Nick Agiazis - 219166833 +Sarah Gosling - 220094149 +Morgaine Barter - 218342547 +Lily Lan - 220340119 +Bella Chhour - 218620536 +Nguyen Quoc Huy Pham - 219453121 + +## Introduction + +Every Deakin student that has completed unit SIT102 is required to demonstrate their skills and +experience through the development of a game using the Splashkit library. We’ve had the privilege of +seeing screenshots and captures of these awesome projects, but very rarely have we had the +opportunity to play these games. + +The main purpose of this project is to provide a platform for these students to showcase their +original Splashkit developments in an eye-catching, easy-to-use application. This application can +then be deployed on different hardware systems, allowing future development to take this to the next +level by creating a physical Arcade machine for Deakin! + +This also gives students motivation to continue to develop and refine game projects. + +## Intended Audience + +The main intention is to allow a wide demographic to contribute to the Arcade machine with their own +Splashkit game developments. + +It will be a great showpiece for Deakin open days, where the public and aspiring students can +experience the creation of past students. + +Games are an attraction to different age groups, this functionality of providing games and an +article including content to help create similar games would be helpful for interested individuals. + +## Intended Use + +Ideally, any Deakin student may download and run the application on their respective device, so even +cloud students will get the opportunity to play the game their friend made! The application will +store all eligible student creations and support the selection and launching of games. + +We will initially be developing the application specifically for Windows machines, but the intention +is that the application will be compatible across the three major operating systems, Windows, OSX +and Raspbian which will be great to advertise what is possible with SplashKit to future students. + +The intended use for the how-to-build-a-game documentation is to help guide beginner programmers in +making 2D games using SplashKit. + +We aim to showcase all SplashKit functionality across different games and provide examples/use cases +to use alongside the SplashKit.io documentation for faster upskilling of future students (and will +be uploaded to SplashKit.io in the future if of a high standard). + +This will also provide detailed information on the requirements for the application to be deployed +on the Arcade Machine. + +## Scope + +This trimester we will endeavor to construct a prototype of the application as well as GitHub +repository, with clear instructions for students to upload their game creations. A Windows +application which will automatically fetch new games from the repository and load them into the +Arcade machine menu. This application will also allow users to select a game of their choice, start +and play the game, and allow for audio options and window control. + +Next trimester the company intends to construct a physical Arcade Machine to run the software, prior +to this development software changes may be required to port the application from Windows to the +Linux environment. Machine to laptop testing compatibility (key changes for buttons, and joystick) + +Next year and beyond (out of current scope) we aim to keep adding different arcade games to the +machine and test on physical machine. + +## Definitions and Acronyms + +PR = pull request + +QA = Quality Assurance + +SRS = Software Requirements Specification (document/md file for SplashKit Applications) + +2D = Two Dimensional + +RPi = Raspberry pi + +API = Application Programming Interface + +## Overall Description + +## User Needs + +There are several distinct types of users we need to cater for, the user (student) that is intending +to showcase their Splashkit game creation on the Arcade machine, and the user (anyone) that wishes +to play the games. Then there are software developers and engineers who wish to create their own +Arcade machine. + +Students wanting to contribute a game will require documentation to outline the methodology and +requirements to do so. + +Students wanting to develop games will require documentation outlining the best methods of utilizing +the SplashKit API + +A friendly user interface for the Arcade Machine. + +## Assumptions/Dependencies: + +We assume that most users interested in running the software application will be using a Windows +machine. As such, for the scope of this project, a dependency will be to have a functioning Windows +environment. + +We will need to have at least game ready in order to add it to the arcade/showcase. + +We assume most games created will be in 2D and will follow the template provided. + +We also assume that the Raspberry Pi will merge with preconfigured controls without too much +complication. + +## UI/UX considerations: + +• Arcade layout - o Arcade gallery/selection menu UI needs to fit the SplashKit design (palette, +consistent with existing SplashKit style (matches website style, etc) • UI should be user friendly + +## System Features and Requirements + +## Functional Requirements + +There are some requirements. + +Students intending to contribute their game to the platform must abide by the guideline requests in +the GitHub repository documentation. + +Some of these requirements include: + +- Inclusions to the program.cpp file of the student’s game +- ESCAPE_KEY included in quit options, +- Window dimensions to be defined addressing guideline request +- Student must fill out the configuration file to include in PR +- Pull request to the repo +- Arcade machine will have joystick, plus four to six buttons. Games can have the capability to use + left, right, up, down plus any use of the four buttons (e.g., jump, fire, etc.) -Arcade machine + will require a button specifically dedicated to opening a ‘menu’ Arcade Machine software + functionality: • Must contain an interface which permits selection of games? - terrible wording • + Straightforward process to download games and receive updates • A manually/automatically vetted + process which imports games into the library +- must be an interactive game/ handles player input (1 or 2 players on one machine) +- no idle games as this does not fit the arcade game requirements + +## External Interface Requirements + +- Window size set to 1920 x 1080 (16:9) HDMI, this is a standard laptop pixel width and height. +- When creating the window use function toggle_window_border() to remove the minimize, maximize and + exit options from the game window visually +- Also, centre the placement of the window and give it a name using the function + window_position_named() + +## System Features + +- Software to eventually be deployable on Raspberry Pi to create a physical Arcade Machine +- Must demonstrate SplashKit functionality within the code. +- Arcade machine must understand/accept SplashKit resources +- Staying Networked (Network accessed forever) + +## Nonfunctional Requirements + +How-to-build documentation for games created so that future students can understand the steps +involved in recreating the game themselves with screenshots and/or video explanation to help show +the process/outline clearly. Guides should be at a beginner's level of programming and could be used +to create their own custom games with a step-by-step plan for which order they should do this in. +For this reason, games have been designed in 2D as this is most common for SplashKit but are not +limited to. + +References: +https://www.perforce.com/blog/alm/how-write-software-requirements-specification-srs-document +(template found at: +https://github.com/thoth-tech/handbook/blob/main/docs/processes/quality-assurance/templates/srs-template.md +) diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposal Template.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposal Template.md new file mode 100644 index 00000000..6f8f3c95 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposal Template.md @@ -0,0 +1,43 @@ +# Title: [Tutorial Title] + +## Introduction + +Provide a brief introduction to the tutorial, explaining what the tutorial will cover and what the +reader will learn from it. + +## Prerequisites + +List any prerequisites or prior knowledge required for the tutorial, such as programming skills, +familiarity with specific tools or libraries, or any other relevant background. + +## Functions Used (Link to Splashkit documentation) + +1. `Function1` +1. `Function2` + +## Table of Contents + +1. **[Section 1 Title]** + - [Subtopic 1] + - [Subtopic 2] + - [Subtopic 3] +1. **[Section 2 Title]** + - [Subtopic 1] + - [Subtopic 2] + - [Subtopic 3] + +## Tutorial Details + +Explain the structure of the tutorial and how it will be presented. Mention the level of difficulty +and the target audience for the tutorial. + +## Expected Learning Outcomes + +List the learning outcomes that the readers can expect after completing the tutorial. What skills +will they have gained, and what will they be able to do with the knowledge acquired? + +## Conclusion + +Summarize the importance of the tutorial and how it will benefit the readers. Reiterate the main +points covered in the tutorial and encourage readers to apply their newfound knowledge in real-world +projects. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Basic Audio Manipulation in Splashkit.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Basic Audio Manipulation in Splashkit.md new file mode 100644 index 00000000..19ceba57 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Basic Audio Manipulation in Splashkit.md @@ -0,0 +1,72 @@ +# Title: Introduction to Splashkit Audio and Music Functions + +## Introduction + +In this tutorial, you will learn how to work with audio and music in the Splashkit framework. We +will explore various functions that allow you to load, play, pause, and control music tracks within +your Splashkit projects. By the end of this tutorial, you will have a solid understanding of how to +incorporate background music into your games or applications using Splashkit. + +## Prerequisites + +Before diving into this tutorial, it is essential to have the following prerequisites: + +1. **Basic Programming Knowledge:** Familiarity with programming concepts and a general + understanding of coding practices. +1. **C++/C# Programming Language:** Understanding of the C++ and/or C# programming languages, + including variables, functions, loops, and conditional statements. +1. **Integrated Development Environment (IDE):** An IDE set up for C development, such as + [Visual Studio Code](https://code.visualstudio.com/) +1. **Splashkit Framework:** Installation of the Splashkit framework on your system. You can find + installation instructions for your operating system on the + [Splashkit website](https://splashkit.io/articles/installation/). + +## Functions Used (Link to Splashkit documentation) + +1. [load_music](https://splashkit.io/api/audio/#load-music) +1. [music_filename](https://splashkit.io/api/audio/#music-filename) +1. [music_name](https://splashkit.io/api/audio/#music-name) +1. [music_named](https://splashkit.io/api/audio/#music-named) +1. [play_music](https://splashkit.io/api/audio/#group-play-music) +1. [pause_music](https://splashkit.io/api/audio/#pause-music) +1. [resume_music](https://splashkit.io/api/audio/#resume-music) +1. [stop_music](https://splashkit.io/api/audio/#stop-music) +1. [music_playing](https://splashkit.io/api/audio/#music-playing) +1. [music_volume](https://splashkit.io/api/audio/#music-volume) +1. [fade_music_in](https://splashkit.io/api/audio/#group-fade-music-in) +1. [fade_music_out](https://splashkit.io/api/audio/#fade-music-out) + +## Table of Contents + +1. **Introduction to Splashkit Audio and Music** +1. **Loading and Playing Music** + 1. Load music from file. + 1. Get music file name. + 1. Get music name by index. + 1. Play, pause, resume, and stop music. + 1. Check if music is currently playing. +1. **Controlling Music Volume** + 1. Adjusting the music volume. + 1. Fading music in and out. + +## Tutorial Details + +This tutorial is designed for beginners with a basic understanding of programming and the C++ +language. We will cover fundamental audio functions provided by Splashkit, focusing on loading and +playing music tracks. The tutorial will be presented in a step-by-step manner, providing clear +examples and explanations along the way. + +## Expected Learning Outcomes + +By the end of this tutorial, you will have gained the following skills: + +- Loading music tracks from files and accessing their information. +- Playing, pausing, resuming, and stopping music. +- Adjusting the volume of music. +- Fading music in and out for smooth transitions. + +## Conclusion + +Understanding how to work with audio and music is essential for creating engaging and immersive +experiences in your Splashkit projects. By mastering the functions covered in this tutorial, you +will be equipped to incorporate background music seamlessly into your games or applications. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Building the SplashKit Core Library with CMake.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Building the SplashKit Core Library with CMake.md new file mode 100644 index 00000000..43a467a3 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Building the SplashKit Core Library with CMake.md @@ -0,0 +1,83 @@ +## Title: Understanding CMakeLists.txt for Building the SplashKit Core Library + +As a Splashkit developer I want to learn how the CMakeLists.txt file works for building the +SplashKit core library, So that I can effectively compile and link SplashKit on various platforms +for my game development and multimedia projects. + +### Introduction + +This tutorial aims to provide readers with a basic understanding of the CMakeLists.txt file used for +building the SplashKit core library. CMake is a powerful build system generator that simplifies the +process of compiling and linking projects across different platforms. By the end of this tutorial, +readers will have a solid grasp of how CMakeLists.txt works for building SplashKit and will be able +to modify it for their own projects. + +### Prerequisites + +Readers should have: + +- Basic knowledge of C++ programming language. +- Familiarity with CMake and its basic syntax. + +### Functions Used + +1. None + +### Table of Contents + +1. **Introduction to CMakeLists.txt** + + - Understanding the purpose of CMakeLists.txt. + - The role of CMakeLists.txt in building SplashKit. + - Basic CMake syntax. + +1. **Directory Setup and Platform Detection** + + - Setting up directories for the SplashKit project. + - Detecting the current platform (Windows, macOS, Linux). + +1. **Linking Libraries and Frameworks** + + - Configuring library and framework flags for different platforms. + - Linking SplashKit with external dependencies. + +1. **Source Files and Includes** + + - Organising source files for building the SplashKit core library. + - Including directories and header files. + +1. **Building the SplashKit Core Library** + + - Creating the SplashKit shared library. + - Compiling and linking on Windows (MINGW), macOS, and Linux. + +1. **Modifying CMakeLists.txt for Custom Projects** + - Adapting CMakeLists.txt for custom projects. + - Adding new source files and directories. + - Linking additional libraries. + +### Tutorial Details + +This tutorial will provide a comprehensive explanation of the CMakeLists.txt file used to build the +SplashKit core library. It will cover directory setup, platform detection, linking libraries, +handling source files, and compiling the shared library on different platforms. The tutorial is +aimed at computer science students and programmers who want to gain a deeper understanding of CMake +and learn to customise it for their projects. + +### Expected Learning Outcomes + +After completing this tutorial, readers will: + +- Understand the structure and purpose of CMakeLists.txt in building the SplashKit core library. +- Know how to configure CMake for different platforms (Windows, macOS, Linux). +- Be able to link libraries and frameworks with the SplashKit project. +- Learn how to organise source files and include directories effectively. +- Feel confident in modifying CMakeLists.txt for their own projects. + +### Conclusion + +Understanding CMakeLists.txt is a valuable skill for readers interested in managing complex build +processes. By mastering the concepts presented in this tutorial, readers will be well-equipped to +work with CMake and customise it according to the requirements of their projects. So, let's delve +into the world of CMake and unleash the full potential of SplashKit in game development and +multimedia applications! diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Mouse Button and Inputs.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Mouse Button and Inputs.md new file mode 100644 index 00000000..bc3263ac --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Mouse Button and Inputs.md @@ -0,0 +1,82 @@ +# Tutorial Proposal + +## Title: Getting Started With Mouse Button and Inputs + +### Introduction + +As a Splashkit developer, I want to learn how to use `Mouse Button` in Splashkit so that I can +identify which key triggers an event and handle it accordingly. + +### Prerequisites + +- Basic understanding of data types +- Basic understanding of at least one SplashKit supported programming languages + +### Functions Used (Link to Splashkit documentation) + +1. [Hide Mouse](https://splashkit.io/api/input/#hide-mouse) +1. [Mouse Clicked](https://splashkit.io/api/input/#mouse-clicked) +1. [Mouse Down](https://splashkit.io/api/input/#mouse-down) +1. [Mouse Movement](https://splashkit.io/api/input/#mouse-movement) +1. [Mouse Position](https://splashkit.io/api/input/#mouse-position) +1. [Mouse Position Vector](https://splashkit.io/api/input/#mouse-position-vector) +1. [Mouse Shown](https://splashkit.io/api/input/#mouse-shown) +1. [Mouse Up](https://splashkit.io/api/input/#mouse-up) +1. [Mouse Wheel Scroll](https://splashkit.io/api/input/#mouse-wheel-scroll) +1. [Mouse X](https://splashkit.io/api/input/#mouse-x) +1. [Mouse Y](https://splashkit.io/api/input/#mouse-y) +1. [Move Mouse](https://splashkit.io/api/input/#group-move-mouse) +1. [Show Mouse](https://splashkit.io/api/input/#group-show-mouse) + +### Table of Contents + +1. **Introduction to Mouse Button** + - What is `Mouse Button`? + - List of `Mouse Button` +1. **Mouse Button Inputs** + - Mouse Clicked + - Mouse Down + - Mouse Up + - Demonstration +1. **Read Mouse Movement** + - Mouse Movement + - Mouse Wheel Scroll + - Demonstration +1. **Mouse Position** + - Mouse Position + - Mouse Position Vector + - Mouse X + - Mouse Y + - Move Mouse + - Demonstration +1. **Mouse Visibility** + - Hide Mouse + - Show Mouse + - Mouse Shown + - Demonstration + +### Tutorial Details + +The tutorial will first introduce `Mouse Button` data type since an understanding of this is +important to be able to apply them to the functions that will also be discussed here. Next, each +section will explain all SplashKit functions to read and handle mouse inputs. Each function will be +given a description of its use and syntax, and at the end of each section there can be an example or +demonstration of how the functions are used. + +This tutorial is suitable for beginners wanting to learn how to handle mouse inputs. It is targetted +to people who are getting started on handling inputs for their SplashKit games and people who need a +list of `Mouse Button` and functions for syntax help. + +### Expected Learning Outcomes + +After completing this tutorial, readers will be able to: + +1. Understand what `Mouse Button` is and how to use it. +1. Know which `Mouse Button` to use to handle mouse inputs. +1. Understand and apply mouse input handling functions on SplashKit. + +### Conclusion + +This tutorial is beneficial for beginners who are wanting to start handling mouse inputs for their +SplashKit game. It is necessary to understand how to find which `Mouse Button` and functions to use +to implement them to their games. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With SplashKit Database.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With SplashKit Database.md new file mode 100644 index 00000000..b05fe3d7 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With SplashKit Database.md @@ -0,0 +1,94 @@ +# Tutorial Proposal + +## Title: Getting Started With SplashKit Database + +### Introduction + +As a Splashkitdeveloper, I need to understand how to work with databases in Splashkit to store and +manage data and user information efficiently. + +### Prerequisites + +- Base understanding of SplashKit +- Basic C++ programming knowledge +- Basic knowledge of SQL or databases + +### Functions Used (Link to Splashkit documentation) + +1. [Open Database](https://splashkit.io/api/database/#open-database) +1. [Has Database](https://splashkit.io/api/database/#get-next-row) +1. [Database Named](https://splashkit.io/api/database/#database-named) +1. [Free Database](https://splashkit.io/api/database/#group-free-database) +1. [Free All Databases](https://splashkit.io/api/database/#free-all-databases) +1. [Run Sql](https://splashkit.io/api/database/#group-run-sql) +1. [Query Column For Boolean](https://splashkit.io/api/database/#query-column-for-boolean) +1. [Query Column For Double](https://splashkit.io/api/database/#query-column-for-double) +1. [Query Column For Integer](https://splashkit.io/api/database/#query-column-for-integer) +1. [Query Column For String](https://splashkit.io/api/database/#query-column-for-string) +1. [Query Type Of Col](https://splashkit.io/api/database/#query-type-of-col) +1. [Query Success](https://splashkit.io/api/database/#query-success) +1. [Rows Changed](https://splashkit.io/api/database/#rows-changed) +1. [Free Query Result](https://splashkit.io/api/database/#free-query-result) +1. [Free All Query Results](https://splashkit.io/api/database/#free-all-query-results) +1. [Get Next Row](https://splashkit.io/api/database/#get-next-row) +1. [Has Row](https://splashkit.io/api/database/#has-row) +1. [Reset Query Result](https://splashkit.io/api/database/#reset-query-result) + +### Table of Contents + +1. **Introduction** + - What is SplashKit Database? + - Usage +1. **Opening Database on SplashKit** + - Database + - Open Database + - Has Database + - Database Named + - Free Database + - Free All Databases + - Demonstration +1. **Performing a Query on the Database** + - Query Result + - Run Sql + - Query Column For Boolean + - Query Column For Double + - Query Column For Integer + - Query Column For String + - Query Type Of Col + - Query Success + - Rows Changed + - Free Query Result + - Free All Query Results + - Demonstration +1. **Iterating Through a Database** + - Get Next Row + - Has Row + - Reset Query Result + - Demonstration + +### Tutorial Details + +The tutorial starts by introducing SplashKit's database library and some examples of its usage. +Then, the next sections will explain functions related to the database and queries used on +SplashKit. Each function will have an explanation on its syntax and usage. Each section will have a +demonstration showing an example of the functions being used. + +This tutorial is suitable for begginers wanting to learn how to handle database on SplashKit. It is +targeted for people who have had a base understanding of SplashKit from previous tutorials who want +to implement database on their games. + +### Expected Learning Outcomes + +After completing this tutorial, readers will be able to: + +1. Understand database handling in SplashKit +1. Use database handling functions on SplashKit +1. Apply database on their SplashKit games such as to record scores, player profiles, game data, + etc. + +### Conclusion + +This tutorial is beneficial for beginners who are wanting to start using database for their +SplashKit game. It is necessary to understand how to handle database and queries functions to use to +implement them to their games for various usage such as recording scores, player profiles, and game +data. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Sprite Layering In Splashkit - C#.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Sprite Layering In Splashkit - C#.md new file mode 100644 index 00000000..b2f34f8e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Sprite Layering In Splashkit - C#.md @@ -0,0 +1,62 @@ +# Tutorial Proposal + +## Title: Getting Started With Sprite Layering In Splashkit - C# + +### Introduction + +A brief introduction into managing sprite layers, understanding rendering order, and organization of +sprites to create visually appealing scenes without excess Sprite / Bitmap management. + +### Prerequisites + +- Basic Sprite handling knowledge as outlined in 'Getting Started With Sprites In Splashkit' +- Basic programming knowledge. Understand the process of declaring and assigning variables. + Understand what an overloaded method is. Understand argument passing and method constructing. +- Basic folder structure knowledge, at most understand how to point to a local file (for bitmap + purposes) + +### Functions Used (Link to Splashkit documentation) + +1. [Create Sprite](https://splashkit.io/api/sprites/#create-sprite) +2. [Sprite Add Layer](https://splashkit.io/api/sprites/#sprite-add-layer) +3. [Bring Layer Forward ](https://splashkit.io/api/sprites/#sprite-bring-layer-forward) +4. [Sprite Bring Layer To Front](https://splashkit.io/api/sprites/#sprite-bring-layer-to-front) +5. [Sprite Hide Layer](https://splashkit.io/api/sprites/#sprite-hide-layer-named) +6. [Sprite Toggle Layer Visible](https://splashkit.io/api/sprites/#sprite-toggle-layer-visible-named) + +### Table of Contents + +1. **[Creation of a layered Sprite]** + + - Small overview of a practical use-case that is referenced throughout tutorial (morning/night + background?) + - Declaration and instantiation of a layered Sprite + - Adding layers and hiding layers + +2. **[Creation of practical use case]** + + - Show practical instantiation of previously taught concepts for a more practical use case (maybe + for first section, use explicit sprites that are labelled for easier tutorial understanding, + one in the corner or information drawn onto the sprite for example) + - Highlight use cases for sprite layers (shifting background maybe) + +### Tutorial Details + +The structure of the tutorial will be a series of guided instructions with screenshots and code +snippets. It will be formatted in markdown for easier future porting to Docusaurus or other document +sharing services. + +### Expected Learning Outcomes + +The learning outcome that the reader can expect to have gained after completing this series of +tutorials is to have gained an understanding of Sprite Layering, including a theoretical +understanding of the concept including how Splashkit specifically interacts with layered sprites, as +well as a practical showcase of the concept + +### Conclusion + +The importance of this tutorial comes from the required ability to be able further interact with +Sprites as apart of the Splashkit library. Easing workflows and system process management via Sprite +layering rather than raw Sprite manipulation and management allows for a greater understanding of +the framework and concept as a whole and further entrenches students with the ability to use and +understand Sprites. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Sprites in Splashkit Outline - C#.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Sprites in Splashkit Outline - C#.md new file mode 100644 index 00000000..47448847 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started With Sprites in Splashkit Outline - C#.md @@ -0,0 +1,61 @@ +# Tutorial Proposal + +## Title: Getting Started With Sprites in Splashkit Outline - C# + +### Introduction + +A brief introduction into handling Sprites - specifically X/Y positioning, with an initial beginner +focus on drawing a sprite to the screen, as well as accessing and modifying sprite positional data +based off of X and Y coordinates over time, with a section of general outline of Sprite handling +theory, methods, and modes of thinking in relation to Sprites in Splashkit. + +### Prerequisites + +- Basic programming knowledge. Understand the process of declaring and assigning variables. + Understand what an overloaded method is. Understand argument passing and method constructing. +- Basic folder structure knowledge, at most understand how to point to a local file (for bitmap + purposes) + +### Functions Used (Link to Splashkit documentation) + +1. [Create Sprite](https://splashkit.io/api/sprites/#create-sprite) +2. [Draw Sprite](https://splashkit.io/api/sprites/#group-draw-sprite) +3. [Move Sprite To](https://splashkit.io/api/sprites/#move-sprite-to) +4. [Sprite X](https://splashkit.io/api/sprites/#sprite-x) +5. [Sprite Y](https://splashkit.io/api/sprites/#sprite-y) + +### Table of Contents + +1. **[Understanding Sprites in Splashkit]** + + - Basic process of instantiating bitmap and sprite objects + - Understanding overloaded methods of above + +2. **[Placing Sprites into a Splashkit window]** + + - Using Create Sprite, Draw Sprite, and Move Sprite To to see our sprite and modify position + +3. **[Using Splashkit to move our Sprite around]** + + - Construction of some basic small program to showcase active runtime modification of Sprite + positioning and drawing. Maybe showcase multiple sprites, or maybe a random movement of a + single sprite. + +### Tutorial Details + +The structure of the tutorial will be a series of guided instructions with screenshots and code +snippets. It will be formatted in markdown for easier future porting to Docusaurus or other document +sharing services. + +### Expected Learning Outcomes + +The learning outcome that the reader can expect to have gained after completing this series of +tutorials is to have a basic understanding of Sprite assertion and manipulation, so as to be able to +use Sprites in their own projects. + +### Conclusion + +The importance of this tutorial comes from the almost ubiquitous required ability to be able to +interact with Sprites in the process of making games. Splashkit being a visual-focused and friendly +game making frontend, understanding how to interact with that visual medium via Sprites as a +baseline is important. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started in Splashkit Outline.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started in Splashkit Outline.md new file mode 100644 index 00000000..3c08aefa --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Getting Started in Splashkit Outline.md @@ -0,0 +1,96 @@ +# Tutorial Proposal + +## Title: Getting Started: C++, C#, Python, and Pascal - Windows + +### Introduction + +A brief introduction into creating a splashkit project for all 4 supported languages, marked by +successful use of the `skm new` command on windows as well as a successful compile call. + +### Prerequisites + +- Basic computer knowledge. Ability to install files, run commands from a Command Line +- Basic troubleshooting abilities, PATH environment variable editing (will be covered in the + tutorial but useful to have pre-existing knowledge) + +### Functions Used (Link to Splashkit documentation) + +1. [Write](https://splashkit.io/api/terminal/#write) + +### Table of Contents + +1. **[Installing and compiling a C++ Splashkit programme on windows]** + + - Installation of the MSYS2 terminal + - Installation of the Splashkit SDK + - Installation of Visual Studio Code / Language Tools + - Hello World compile + +2. **[Installing and compiling a C# Splashkit programme on windows]** + + - Installation of the MSYS2 terminal + - Installation of the Splashkit SDK + - Installation of Visual Studio Code / Language Tools + - Hello World compile + +3. **[Installing and compiling a Python Splashkit programme on windows]** + + - Installation of the MSYS2 terminal + - Installation of the Splashkit SDK + - Installation of Visual Studio Code / Language Tools + - Hello World compile + +4. **[Installing and compiling a Pascal Splashkit programme on windows]** + + - Installation of the MSYS2 terminal + - Installation of the Splashkit SDK + - Installation of Visual Studio Code / Language Tools + - Hello World compile + + Maybe consolidate first two/three steps into a single tutorial, it would just be copy-pasting the + first parts of each to every other otherwise. Maybe that would be OK though, given that it's + meant to be beginner-focused, having copies of the same beginner friendly installation + instructions might not be that bad? + + ### Table of Contents. ALT + + 1. **[Installing MSYS2 and Splashkit SDK on windows]** + + - Installation of the MSYS2 terminal + - Installation of the Splashkit SDK + + 2. **[Installing Visual Studio Code / FreePascal(?) on windows]** + + - Installation of Visual Studio Code + - More research to be done on Pascal installation and compilation processes, have got every other + langauge down except this one, FreePascal is an IDE and Compiler, trying to see if it can be + rooted into VSCode, as well as how to get splashkit to be identified successfully without + compile errors + + 3. **[Hello Splashkit on windows]** + + - C++ Hello World compile tutorial + - C# Hello World compile tutorial + - Python Hello World compile tutorial + - Pascal Hello World compile tutorial + +### Tutorial Details + +The structure of the tutorial will be a series of guided instructions with screenshots and code +snippets. It will preferably be formatted in markdown, but further discussion regarding this has to +take place. The target audience will be absolute beginners, with little pre-knowledge outside of +general computer use expected. + +### Expected Learning Outcomes + +The learning outcome that the reader can expect to have gained after completing this series of +tutorials is to be able to go from nothing to be able to compile splashkit programmes with different +languages. This gives them the tools and abilities to compile files for later use in tutorials and +general overall use of the program, as well as facilitate different language usage and learning. + +### Conclusion + +The importance of this tutorial comes from the required ability to be able to install, as well as +compile splashkit programmes in multiple languages. This will benefit the readers by giving them the +necessary baseline to be able to learn more and facilitate real-world projects via installation of +the Splashkit SDK, IDEs and Language Tools, and a practical understanding of the compiling pipeline. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Introduction to Key Codes.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Introduction to Key Codes.md new file mode 100644 index 00000000..d0973786 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Introduction to Key Codes.md @@ -0,0 +1,56 @@ +# Tutorial Proposal + +## Title: Introduction to Key Codes + +### Introduction + +As a Splashkit developer, I want to learn how to use `Key Code` in Splashkit so that I can identify +which key triggers an event and handle it accordingly. + +### Prerequisites + +Readers should have: + +- Basic understanding of data types + +### Functions Used (Link to Splashkit documentation) + +1. [Key Name](https://splashkit.io/api/input/#key-name) + +### Table of Contents + +1. **Introduction to Key Codes** + - What are key codes? + - List of key codes + - How key codes are used +1. **Key Name** + - Syntax + - Usage and example + +### Tutorial Details + +The tutorial will first introduce the `Key Code` data type and how it is used. The list of key codes +are presented as a table, with the following collumns: Name, Description, Picture. The picture can +show an illustration of the associated key on a keyboard. The usage subtopic can briefly mention +some of the keyboard input functions that use `Key Code` as parameter, which links to the tutorials +for each of those functions. + +This tutorial is suitable for beginners as an introduction to keyboard inputs. It is targetted to +people who are getting started on handling inputs for their SplashKit games and people who need a +list of keyboard inputs and their associated `Key Code`. + +### Expected Learning Outcomes + +After completing this tutorial, readers will be able to: + +1. Understand what `Key Code` is and how to use it. +1. Know which `Key Code` to use to handle keyboard inputs. +1. Retrieve string name for a given `Key Code` by using the `Key Name` function. + +### Conclusion + +This tutorial is beneficial for beginners who are wanting to start handling keyboard inputs for +their SplashKit game. It is necessary to understand how to find which `Key Code` to use to swiftly +implement it to their games, instead of trying to find them through trial-and-error. This tutorial +can also provide base knowledge in understanding keyboard input functions that may be outlined in +another tutorial. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Splash World Adventures.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Splash World Adventures.md new file mode 100644 index 00000000..60f39a7e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Splash World Adventures.md @@ -0,0 +1,249 @@ +## Software Requirements Specification for Mario-Like Game Tutorial Using Splashkit + +### 1. Purpose Description + +The purpose of this game tutorial is to create an engaging and educational Mario-like game that +utilizes various functionalities of Splashkit. + +The tutorial aims to teach users how to implement key game mechanics and features, such as character +movement, collision detection, sprite animation, and interactive gameplay. + +By building this game, users will gain hands-on experience with Splashkit's capabilities and learn +how to apply them effectively in real-world game development scenarios. + +### 2. Features + +The Mario-like game tutorial will include the following **features**: + +1. **Character Movement**: Implementing smooth movement for the main character using keyboard input. +1. **Collision Detection**: Handling collisions between the main character and other game objects, + such as obstacles and enemies. +1. **Sprite Animation**: Creating animations for the main character, enemies, and other in-game + elements using Splashkit's animation functionalities. +1. **Interactive Gameplay**: Designing interactive elements like collectible items, power-ups, and + enemies to provide an engaging gaming experience. +1. **Scoring System**: Implementing a scoring mechanism to track and display the player's progress. + _Stretch_: different scene via states system +1. **Audio Integration**: Incorporating sound effects and background music using Splashkit's audio + functionalities. +1. **Level Design**: Creating multiple levels with increasing difficulty and unique challenges. + +#### Stretch Features + +Menu system to start the game. Utilizes mouse input and States to change scenes using Splashkit game +engine. + +### 3. User Case + +As a user, I want to follow the Mario-like game tutorial to **learn how to develop** a game using +Splashkit's functionalities effectively. + +--- + +The tutorial should provide step-by-step instructions on implementing key game mechanics, including +character movement, collision detection, sprite animation, interactive gameplay, scoring system, +audio integration, and level design. By engaging in the tutorial, I aim to gain practical experience +in game development with Splashkit, understand its features, and apply the learned knowledge to +create my own games with similar functionalities. + +--- + +**Stretch User story** + +As a prospective Deakin University student, I want to play the Mario-like game developed using +Splashkit at the Deakin Arcade Showcase, so that I can experience and appreciate the programming +skills showcased at Deakin and get inspired to learn programming myself. + +### 4. Class Diagram + +This is a high-level plan of the game + +```mermaid +classDiagram + class Game { + -gameEngine: IGameEngine + } + class IRenderer { + <> + Init()*: void + Clear()*: void + RenderObject()*: void + Present()*: void + Shutdown()*: void + } + class SplashkitRenderer { + Init(): void + Clear(): void + RenderObject(): void + Present(): void + Shutdown(): void + } + + class ILogger { + <> + +Log(): void + +LogError(): void + +LogException(): void + +LogFormat(): void + +LogWarning(): void + } + + class SplashkitLogger { + +logEnabled: bool + +IsLogTypeAllowed(): bool + +Log(): void + +LogError(): void + +LogException(): void + +LogFormat(): void + +LogWarning(): void + } + + class IGameStateManager { + <> + -gameStates: stack[GameState] + +changeState()*: void + +getCurrentState()* : GameState* + +popState()* : void + +pushState()* : void + +render()* : void + +update()* : void + } + + class IGameEngine { + <> + #renderer: IRenderer + #gameStateManager: IGameStateManager + #logger: ILogger + +Start()*: void + +Update()*: void + +Draw()*: void + } + + class GameEngine { + #gameStateManager: IGameStateManager + #logger: ILogger + +Start(): void + +Update(): void + +Draw(): void + } + + class GameStateManager { + -gameStates: stack[GameState] + +changeState(): void + +getCurrentState() : GameState* + +popState() : void + +pushState() : void + +render() : void + +update() : void + } + + class IGameState { + <> + +update() + +draw() + } + + class MainMenuState { + +update() + +draw() + } + + class PlayGameState { + +Levels: Level + +update() + +draw() + } + + class IGameLevel { + <> + +gameObjects : vector~GameObject~ + +AddGameObject(GameObject gameObject)* + +RemoveGameObject(GameObject gameObject)* + } + + class GameObject { + <> + #name : str + #components : vector~IComponent~ + #transform: Transform + +GameObject(str name, vector~Icomponent~ components)* + +AddComponent(IComponent component)*: void + +GetComponent(str name)*: self + +RemoveComponent(IComponent component)*: void + +ToString()*: str + } + + class Component { + <> + #gameObject: GameObject + +parent: gameObject + +Awake() + +Start() + +Update() + } + + class Transform { + #gameObject: GameObject + +childCount: int + +hasChanged: bool + +localPosition: Vector2D + +parent: gameObject + +up: Vector2D + +forward: Vector2D + +hasChanged: bool + +Awake() + +Start() + +Update() + +Translate() + } + + Game *-- IGameEngine + IGameEngine <|-- GameEngine: Implements + IRenderer <|-- SplashkitRenderer: Implements + IGameEngine *-- IGameStateManager + IGameEngine *-- ILogger + IGameEngine *-- IRenderer + IGameStateManager <|.. GameStateManager: Implements + ILogger <|.. SplashkitLogger: Implements + PlayGameState o-- IGameLevel + GameStateManager --> IGameState + IGameState <|.. MainMenuState: Implements + IGameState <|.. PlayGameState: Implements + IGameLevel *-- GameObject + GameObject *--* Component + GameObject *-- Transform + Component <|.. Transform: Implements +``` + +### 5. Sequence Diagrams + +```mermaid +sequenceDiagram + participant g as Game + participant gsm as GameStateManager + participant gs as GameState + participant l as IGameLevel + participant go as GameObject + participant c as Component + + g->>gsm: start() + gsm->>gsm: GameStateManager() + gsm->>gs: pushState(MainMenuState) + gsm->>gs: getCurrentState() + Note over gsm,gs: Current state is now MainMenuState + + g->>gsm: update() + gsm->>gs: update() + Note over gsm,gs: MainMenuState update is called + + gsm->>gs: changeState(PlayGameState) + gsm->>gs: getCurrentState() + Note over gsm,gs: Current state is now PlayGameState + + g->>gsm: update() + gsm->>gs: update() + gs->>l: update() + l->>go: update() + go->>c: Update() + +``` diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Mouse Button and Inputs.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Mouse Button and Inputs.md new file mode 100644 index 00000000..26a7fe01 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Mouse Button and Inputs.md @@ -0,0 +1,277 @@ +# Getting Started With Mouse Button and Inputs + +## Introduction to Mouse Button + +### What is `Mouse Button`? + +`Mouse Button` is an enumeration used by SplashKit to read inputs from the mouse to be handled on +your program. If you want to have users control your program using the mouse, then you must +understand `Mouse Button`! + +### List of `Mouse Button` + +| Name | Description | +| --------------- | ----------------------- | +| NO_BUTTON | No mouse button | +| LEFT_BUTTON | The left mouse button | +| MIDDLE_BUTTON | The middle mouse button | +| RIGHT_BUTTON | The right mouse button | +| MOUSE_X1_BUTTON | The x1 mouse button | +| MOUSE_X2_BUTTON | The x2 mouse button | + +## Mouse Button Inputs + +Here are some functions that are used to handle mouse button inputs. These functions takes in the +`Mouse Button` as parameter and checks if the specified button has been clicked, held down, or +released. + +### Mouse Clicked + +`Mouse Clicked` is a boolean function that checks if the specified `Mouse Button` has been clicked +since the last time `Process Events` was called. + +Syntax in C++: + +`bool mouse_clicked(mouse_button button)` + +### Mouse Down + +`Mouse Down` checks if the specified button is being held down. + +Syntax in C++: + +`bool mouse_down(mouse_button button)` + +### Mouse Up + +Opposite from the previous function, `Mouse Up` checks if the specified button is being held up (not +pressed). + +Syntax in C++: + +`bool mouse_up(mouse_button button)` + +### Demonstration + +Here is an example of all the mouse input functions being used together. + +``` +int main() +{ + open_window("Game", 800, 600); + + while(!key_down(ESCAPE_KEY)) + { + process_events(); // check mouse state + + if (mouse_clicked(LEFT_BUTTON)) // check if left mouse button is clicked + { + clear_screen(COLOR_RED); + } + else if (mouse_down(LEFT_BUTTON)) // check if left mouse button is pressed down + { + clear_screen(COLOR_YELLOW); + } + else if (mouse_up(LEFT_BUTTON)) // check if left mouse button is released + { + clear_screen(COLOR_GREEN); + } + + refresh_screen(60); + } + + return 0; +} +``` + +In this example, the screen will turn red if the left mouse button is clicked, which is checked in +the first if clause. In the next loop, if the mouse has not just been clicked but is still being +held down, the screen will turn yellow. Meanwhile, if the left mouse button is released, the screen +will turn green. + +## Read Mouse Movement + +Another thing we can do with a mouse other than pressing its buttons is moving it around. So, we +should also understand the functions to handle mouse movement to use it on our program. + +### Mouse Movement + +`Mouse Movement` is a function that returns the amount of accumulated mouse movement since the last +time `Process Events` was called. It returns the value as a `Vector 2D` data type, which shows the +direction and distance in the x and y scale. + +Syntax in C++: + +`vector_2d mouse_movement()` + +### Mouse Wheel Scroll + +`Mouse Wheel Scroll` returns the distance and direction of the mouse scroll since the last time +`Process Events` was called. Like the previous function, this function returns the `Vector 2D` data +type. + +Syntax in C++: + +`vector_2d mouse_wheel_scroll()` + +### Demonstration + +``` +int main() +{ + vector_2d movement; + + vector_2d scroll; + + open_window("Game", 800, 600); + + while(!key_down(ESCAPE_KEY)) + { + clear_screen(COLOR_BLACK); + + process_events(); // check mouse state + + movement = mouse_movement(); // This stores the mouse movement direction and distance to the movement variable + + scroll = mouse_whell_scroll(); // This stores the mouse wheel scroll direction and distance to the scroll variable + + draw_text("The mouse has moved: " + vector_to_string(movement), COLOR_WHITE, 100, 300); // Print out mouse movement + + draw_text("The mouse wheel scrolled: " + vector_to_string(scroll), COLOR_WHITE, 100, 400); // Print out mouse wheel scroll + + refresh_screen(60); + } + + return 0; +} +``` + +## Mouse Position + +Now that we have learned how to handle mouse inputs and movements, we should also learn how to +handle the mouse's position. Getting the mouse position can be used in your program to make the +experience more interactive. Combined with the mouse input functions, it can be used to spawn items +where the player clicked or respond to the player clicking where an item is located. Not only +getting the position, we can also move the mouse to a specified position using the `Move Mouse` +function. + +### Mouse Position + +`Mouse Position` returns the position of the mouse in the current window as a `Point2d` data type, +which is its x and y coordinates. + +Syntax in C++: + +`point_2d mouse_position()` + +### Mouse Position Vector + +`Mouse Position Vector` returns the position of the mouse relative to the window origin as a +`Vector 2D`. + +Syntax in C++: + +`vector_2d mouse_position_vector()` + +### Mouse X + +`Mouse X` returns a `float` of the distance of the mouse from the left edge of the window. + +Syntax in C++: + +`float mouse_x()` + +### Mouse Y + +`Mouse Y` returns a `float` of the distance of the mouse from the top edge of the window. + +Syntax in C++: + +`float mouse_y()` + +### Move Mouse + +`Move Mouse` moves the cursor to the specified location. This function has two versions, one with +the x and y locations as parameters, and one with a `point2d` as its parameter. + +Syntax in C++: + +`void move_mouse(double x, double y)` + +`void move_mouse(point_2d point)` + +### Demonstration + +This example shows moving the mouse a few pixels from the current position. + +``` +void move_10_point() +{ + double current_x = mouse_x(); // Get the current x position as a double + double current_y = mouse_y(); // Get the current y position as a double + + move_mouse(current_x + 10, current_y + 10); // Move the cursor 10 point to the x and y direction +} + +int main() +{ + open_window("Game", 800, 600); + + while(!key_down(ESCAPE_KEY)) + { + process_events(); // check mouse state + + if (mouse_clicked(LEFT_BUTTON)) + { + move_10_point(); // Performs the move when the left mouse button is clicked + } + + refresh_screen(60); + } + return 0; +} +``` + +## Mouse Visibility + +Finally, we can also alter the mouse visibility on SplashKit. The following functions handles the +mouse visibility. These can be useful to create a more immersive environment for your game. + +### Hide Mouse + +`Hide Mouse` hides the mouse from the screen. + +Syntax in C++: + +`void hide_mouse()` + +### Show Mouse + +There are two versions of the `Show Mouse` function. The first version shows the mouse to the +screen. + +Syntax in C++: + +`void show_mouse()` + +The second version of the function shows or hides the mouse based on its boolean parameter. If true, +it shows the mouse, while if false, it hides the mouse from the screen. + +Syntax in C++: + +`void show_mouse(bool show)` + +### Mouse Shown + +`Mouse Shown` is a boolean function that checks if the mouse is currently visible or not. + +Syntax in C++: + +`bool mouse_shown()` + +## Conclusion + +From this tutorial, we have learned how to handle the mouse on SplashKit starting from the +`Mouse Button` data type, functions related to mouse inputs, movements, positions, to its +visibility. Now that you have learned these functions, you can handle inputs associated with the +mouse on SplashKit! diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit - C#-C++/Getting Started With Splashkit - C#-C++.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit - C#-C++/Getting Started With Splashkit - C#-C++.md new file mode 100644 index 00000000..0774a24e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit - C#-C++/Getting Started With Splashkit - C#-C++.md @@ -0,0 +1,90 @@ +# Getting Started With SplashKit - Windows C#/C++ + +## Initial install + +The first step to interacting with SplashKit on your system is to +[install the MSYS2 unix terminal environment](https://www.msys2.org/). Leave all values as default, +and don't install onto a PATH (install location) that has spaces in it. + +Then open your newly-installed MSYS2 terminal, and install the git client via the following command: + +``` +pacman -S git --noconfirm --disable-download-timeout +``` + +You can copy this code from this document and paste into the MSYS2 client by either right-clicking +and pasting, or using the shift+insert command. + +The next step is to actually run the install script for SplashKit itself, still in MSYS2, with the +following command: + +``` +bash <(curl -s https://raw.githubusercontent.com/splashkit/skm/master/install-scripts/skm-install.sh) +``` + +To make sure everything has worked, you can restart your terminal, run `skm` as a command (just +those letters, it acts as a call), and you should see the following message: + +``` +Splashkit is installed successfully! +Missing skm command. For help use 'skm help' +``` + +## VSCode and Language Tools + +Assuming everything from above has worked, the next steps are comparatively easier. Just +[install Visual Studio Code](https://code.visualstudio.com/) for a start. For the rest of this +guide, we'll be installing and focusing on C#/C++ language install procedures and compile / creation +routines. + +For C#, this process involves opening your MSYS2 terminal again, and running the following command: + +``` +pacman -S mingw-w64-{x86_64,i686}-gcc mingw-w64-{i686,x86_64}-gdb +``` + +Then going to the [.NET Core SDK](https://dotnet.microsoft.com/en-us/download) download page and +installing it. That's it for C#. For a little added functionality such as Intellisense and code +formatting, install the C# extension in Visual Studio Code as well. This can be done by clicking on +the 4 boxes icon on the bottom of the top left menu, near the magnifying glass, and just typing C# +and clicking install. + +For C++, if you've already run the code snippet above, nothing has to be done. Otherwise, run that +code snippet as well, and then simply install the C++ extension in Visual Studio Code, just like for +C#. + +## Creation and Compiling + +This is the fun part. You've installed some language tools, and SplashKit itself. Now the question +is "How do we actually _make_ something?" In order to set up the necessary files and dependencies +for SplashKit project creation, all you have to do is: + +1. Navigate to a folder to act as a base, as an example my folder path will be + `C:\Users\{User}\Desktop\testSplashKit` + +1. Once there, open a MSYS2 terminal and navigate to that folder with the `cd` (change directory) + command. Either by copy-pasting the path in the windows explorer by just clicking it, or typing + it. You'll know you are in the right position because the location line will change from `~` to + your location, like below: + + ![Screenshot of changing directories](image.png) + +1. Once you have navigated the MSYS2 terminal to the base location that you want your project to be + in, you can run either of the following commands: + + 1. For C#, the command is `skm dotnet new`, which will intialize some VSCode settings, create a + Program.cs file to initially edit, as well as a .csproj file to open + + 1. For C++, the command is `skm new c++`, which will do the same as above, but initialize a cpp + file instead + +1. After having created your project files to edit, and assumedly editing them with some amount of + code, the process to compile and run are as follows: + + 1. For C#, `skm dotnet run` will compile and run but not output an exe, for that functionality + you run `skm dotnet publish` and navigate to the created bin folder file structure to find the + output. + + 1. For C++, `skm clang++ program.cpp` will output an exe compiled and ready to run, can be + ammended with an `-O` parameter to give a file name, such as + `skm clang++ program.cpp -o SpriteLayering` giving you a SpriteLayering.exe diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit - C#-C++/image.png b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit - C#-C++/image.png new file mode 100644 index 00000000..73d48f9f Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit - C#-C++/image.png differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md new file mode 100644 index 00000000..64eb8477 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With SplashKit Database.md @@ -0,0 +1,318 @@ +# Getting Started With SplashKit Database + +## Introduction + +### What is SplashKit Database? + +SplashKit has a database library that allows you to create or load databases and perform queries on +them. These databases are stored in database files, and with functions from the SplashKit library, +we can query and manipulate the database. + +### Usage + +You may have learned the use of database, which is for storing information. On SplashKit, you may +want to use database to store information of different users who have access to the game, such as +levels, high score, or save files. You may also want to use databases when creating data heavy +games, e.g., to store information about all the different items, skills, weapons, etc. available in +game. + +## Opening Database in SplashKit + +### Database + +Accessed databases are stored in the `Database` object. + +### Open Database + +`Open Database` is the function used to access or create a database file. If the filename used in +the parameter is an existing database, it will retrieve and access the file. Otherwise, it will +create a new database file with the provided filename. + +Syntax in C++: + +``` +database open_database(string name, string filename) +``` + +### Has Database + +`Has Database` is a boolean fuction used to check if the database with the given name has been +loaded into the program, and return either true or false accordingly. + +Syntax in C++: + +``` +bool has_database(string name) +``` + +### Database Named + +`Database Named` is a function that retrieves the database that has been opened with +`Open Database`. This is useful when you want to use the database without storing it into a +variable. + +Syntax in C++: + +``` +database database_named(string name) +``` + +### Free Database + +After you have finished using your database, you should free the resource using `Free Database`. +There are two versions of the function, one where you use the database object as the parameter, and +one where you use the name of the database for the parameter. + +Syntax in C++: + +``` +void free_database(database db_to_close) +``` + +``` +void free_database(string name_of_db_to_close) +``` + +### Free All Databases + +Another way of freeing all databases at once is using the `Free All Databases` function. + +Syntax in C++: + +``` +void free_all_databases() +``` + +### Demonstration + +``` +int main() +{ + // Open database named "test" from a file named "test_database" + open_database("test", "test_database"); + + // Check if database has been loaded + if (has_database("test")) + { + // Store database to a variable x + database x = database_named("test"); + } + + // Free the database since we are done + free_all_databases(); + + // Alternatives + // free_database("test"); + // free_database(x); +} +``` + +## Performing a Query on the Database + +### Query Result + +`Query Result` is another important data type related to database. This is used to store the result +after performing a query on a database. + +### Run Sql + +`Run Sql` performs an sql command to the database and returns the result as a `Query Result`. Either +the database object or the string name can be used to pass the database on to the function. + +Syntax in C++: + +``` +query_result run_sql(database db, string sql) +``` + +``` +query_result run_sql(string database_name, string sql) +``` + +### Query Success + +`Query Success` can be used to check if the most recent query on a `Query Result` was successful or +not. Syntax in C++: + +``` +bool query_success(query_result db_result) +``` + +### Query Column For Boolean + +`Query Column For Boolean` is used to access a column of a `Query Result` which consists of booleans +at the current row (the top row). + +Syntax in C++: + +``` +bool query_column_for_bool(query_result db_result, int col) +``` + +### Query Column For Double + +`Query Column For Double` is similar to the previous function, except it is used when the data type +is double. + +Syntax in C++: + +``` +double query_column_for_double(query_result db_result, int col) +``` + +### Query Column For Integer + +Similar to the previous two functions, this has the same usage except it is for integers. + +Syntax in C++: + +``` +int query_column_for_int(query_result db_result, int col) +``` + +### Query Column For String + +The final query column function performs similarly to the other functions, where it is used for +strings. + +Syntax in C++: + +``` +string query_column_for_string(query_result db_result, int col) +``` + +### Query Type Of Col + +`Query Type Of Col` is used to check what the data type of the column is. This is useful when you +don't know what data types are used in the database. + +Syntax in C++: + +``` +string query_type_of_col(query_result db_result, int col) +``` + +### Rows Changed + +This function is used to check how many rows has been changed on a database the last time a changing +query was performed on the database. + +Syntax in C++: + +``` +int rows_changed(database db) +``` + +### Free Query Result + +Similar to a `Database`, we should free `Query Result` that we have finished using. + +Syntax in C++: + +``` +void free_query_result(query_result query) +``` + +### Free All Query Results + +`Free All Query Results` can be used to free all `Query Results` at once. + +Syntax in C++: + +``` +void free_all_query_results() +``` + +### Demonstration + +``` +int main() +{ + // Open database named "users" with a table "Users" and the collumns "UID", "Name" + open_database("users", "users_database"); + + // Create a query result to store results + query_result result; + int uid; + string name; + + // Perform SQL to add a new user + run_sql("users", "INSERT INTO Users VALUES('001', 'John');"); + + // Now, if rows_changed(database_named("users")); is used, it should return 1. + + // Perform SQL to get the whole table + result = run_sql("users", "SELECT * FROM Users;"); + + // Get the values into variables + uid = query_column_for_integer(result, 0); + name = query_column_for_string(result, 1); + + // Free the resources since we are done + free_all_databases(); + free_all_query_results(); +} +``` + +## Iterating Through a Database + +You may have noticed that the `Query Column` functions only get the data from the first row of the +`Query Result`. This section will show you how to access the other rows, and iterating through the +whole table. + +### Get Next Row + +`Get Next Row` checks if there is a valid row and moves you to the next row of the `Query Result`. +It is a boolean function that will return either true or false depending on whether the next row +exists or not. + +Syntax in C++: + +``` +bool get_next_row(query_result db_result) +``` + +### Has Row + +Syntax in C++: + +``` +bool has_row(query_result db_result) +``` + +### Reset Query Result + +Syntax in C++: + +``` +void reset_query_result(query_result db_result) +``` + +### Demonstration + +Sample data of "test_database": + +Table | ID | | ---- | | 0 | | 1 | | 2 | + +``` +int main() +{ + // Open a database from a file "test_database" which has a table "Table" with the collumn "ID" + open_database("test", "test_database"); + + query_result result = run_sql("test", "SELECT * From Table";); + + // Check if there is a valid row since the table may be empty + if (has_row(result)) + { + do + { + int id = query_column_for_integer(result, 0); // This will return the values 0, 1, and 2 + + } while (get_next_row(result)) // Loop while there is a valid next row + } + + free_all_databases(); + free_all_query_results(); +} +``` diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprite Layering in Splashkit Tutorial - C#/Sprite layering in Splashkit Tutorial - C#.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprite Layering in Splashkit Tutorial - C#/Sprite layering in Splashkit Tutorial - C#.md new file mode 100644 index 00000000..33b6fb20 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprite Layering in Splashkit Tutorial - C#/Sprite layering in Splashkit Tutorial - C#.md @@ -0,0 +1,151 @@ +# Getting Started With Sprite layering in Splashkit - C# + +## Understanding Sprite Layers + +If you're reading this, you probably have some idea as to the general make up of `Bitmap` and +`Sprite` instantiation in SplashKit. You might have wondered on how to functionally have `Sprites` +show and disappear as a whole, or wondered if having multiple visual elements meant `Sprite` data +management protocols for each element, rather than packs or layers. Funnily enough, SplashKit has +`Sprite Layer` functionality. + +Initially, we can start our code off as is probably expected, assumption being you have at least two +bitmap objects to reference and have appear "on top" of each other, and have it make some sense. For +us, it's going to be a man, a cowboy hat, and a sherrif's badge. We can start off with simple +initialization of our bitmaps, and even our `Sprite` that we will assign our layers to. + +```csharp +//Creation of Window Object to showcase sprites and layers +Window spriteLayers = new Window("Layering with Sprites!", 800, 800); + +//Instantiation of each bitmap used for CreateSprite() and SpriteAddLayer() +Bitmap bodyBit = new Bitmap("base body", "sprite01.png"); +Bitmap hatBit = new Bitmap("base hat", "sprite02.png"); +Bitmap starBit = new Bitmap("base star", "sprite03.png"); + +Sprite bodySprite = SplashKit.CreateSprite("body", bodyBit); // layer idx 0, name body +``` + +It isn't explicitly said anywhere, but SplashKit creates Sprite objects with a 0th indexing layer. +Since SpriteKit also has functionality for either index or layer name referencing, we can assign a +name for easier understanding, but we're going to be explicitly referencing the indexes of our +bitmap layers from now on. + +With our code at this stage, we basically just have a single-layered `Sprite`. Useful for some +cases, but let's say we want to have user input, or specific functionality of the game "show" layers +of a singular `Sprite`? Well, using our already-defined bitmaps, it's relatively simple. + +```csharp +SplashKit.SpriteAddLayer(bodySprite, hatBit, "hat"); // layer 1 +SplashKit.SpriteAddLayer(bodySprite, starBit, "star"); // layer 2 +``` + +Using `SplashKit.SpriteAddLayer(Sprite, Bitmap, name)`, with our according parameters, we can add +layers to our first `Sprite` object for later use. For reference, if you'd like to confirm that the +layer indexes are correct, or see for yourself for debugging / testing purposes, the function +`SpriteAddLayer()` has a return type of an integer, which corresponds to the assigned layer index +value, which can be wrapped as: + +```csharp +SplashKit.WriteLine(SplashKit.SpriteLayerCount(bodySprite)); +``` + +## Showing and manipulating layers + +So now we have our created `Sprite`, our layers, and we can get to drawing our content to the +screen, simple enough, right? + +```csharp +SplashKit.DrawSprite(bodySprite); +spriteLayers.Refresh(); +SplashKit.Delay(2000); +``` + +And, our layers aren't showing. It's important to know that layers aren't shown by default, so in +order to show our added layers to our initial `Sprite` object, we call a function called +`SplashKit.SpriteShowLayer(Sprite, idx);` with our parameters. For us, this looks something like: + +```csharp +SplashKit.SpriteShowLayer(bodySprite, 1); +SplashKit.DrawSprite(bodySprite); +spriteLayers.Refresh(); +SplashKit.Delay(2000); +``` + +Referencing the 1st layer (remember, 0th based indexing from initialization of a `Sprite` object), +and then re-drawing and refreshing our screen will have the second layer show up as well. Copying +this code for our third, our Man slowly puts on his cowboy hat and earns his sheriff badge. + +But what if you want to hide a layer afterwards? Maybe our Sheriff loses his hat, or his badge? It's +simple enough, we can just call a `SplashKit.SpriteHideLayer(Sprite, idx)` function as follows: + +```csharp +SplashKit.SpriteHideLayer(bodySprite, 2); +SplashKit.DrawSprite(bodySprite); +spriteLayers.Refresh(); +SplashKit.Delay(2000); +``` + +Running and compiling this you'll notice an error, we're not clearing our screen, so when we hide a +layer and redraw, the older drawn `Sprite` that had the layer shown is still visible, causing some +visual discrepencies. This is easily fixed by just adding a `SplashKit.ClearScreen(Color.White)` +line before we draw our sprite with `DrawSprite()`. And the final output is as such (your sprites +will be different, but the functionality should be the same): + +![gif of final output](spritelayerfinal.gif) + +Final code snippet is as follows: + +```csharp + +using System; +using SplashKitSDK; + +namespace spritelayering +{ + public class Program + { + public static void Main() + { + + //Creation of Window Object to showcase sprites and layers + Window spriteLayers = new Window("Layering with Sprites!", 800, 800); + + //Instantiation of each bitmap used for CreateSprite() and SpriteAddLayer() + Bitmap bodyBit = new Bitmap("base body", "sprite01.png"); + Bitmap hatBit = new Bitmap("base hat", "sprite02.png"); + Bitmap starBit = new Bitmap("base star", "sprite03.png"); + + //Creating initial Sprite and adding Layers + Sprite bodySprite = SplashKit.CreateSprite("body", bodyBit); // layer 0 + SplashKit.SpriteAddLayer(bodySprite, hatBit, "hat"); // layer 1 + SplashKit.SpriteAddLayer(bodySprite, starBit, "star"); // layer 2 + + //Initial draw: one (base) layer shown + SplashKit.DrawSprite(bodySprite); + spriteLayers.Refresh(); + SplashKit.Delay(2000); + + //First re-draw, two layers shown + SplashKit.SpriteShowLayer(bodySprite, 1); + SplashKit.ClearScreen(Color.White); + SplashKit.DrawSprite(bodySprite); + spriteLayers.Refresh(); + SplashKit.Delay(2000); + + //Second re-draw, three layers shown + SplashKit.SpriteShowLayer(bodySprite, 2); + SplashKit.ClearScreen(Color.White); + SplashKit.DrawSprite(bodySprite); + spriteLayers.Refresh(); + SplashKit.Delay(2000); + + //Third re-draw, two layers shown, one removed + SplashKit.SpriteHideLayer(bodySprite, 2); + SplashKit.ClearScreen(Color.White); + SplashKit.DrawSprite(bodySprite); + spriteLayers.Refresh(); + SplashKit.Delay(2000); + } + } +} +``` diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprite Layering in Splashkit Tutorial - C#/spritelayerfinal.gif b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprite Layering in Splashkit Tutorial - C#/spritelayerfinal.gif new file mode 100644 index 00000000..2e70d85c Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprite Layering in Splashkit Tutorial - C#/spritelayerfinal.gif differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/image.png b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/image.png new file mode 100644 index 00000000..6c9fe47b Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/image.png differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/image2.png b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/image2.png new file mode 100644 index 00000000..98420257 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/image2.png differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/movingsun.gif b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/movingsun.gif new file mode 100644 index 00000000..30cedaa3 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Getting Started With Sprites in Splashkit Tutorial - C#/movingsun.gif differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Introduction to Key Codes.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Introduction to Key Codes.md new file mode 100644 index 00000000..e1c67389 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Introduction to Key Codes.md @@ -0,0 +1,189 @@ +# Introduction to Key Codes + +## Introduction to Key Codes + +### What are key codes? + +`Key Code` is an enumeration used by SplashKit to read inputs from the keyboard to be handled on +your program. Each key code correlates to a key on a keyboard, for example `SPACE_KEY` means the +space key on the keyboard. + +### List of key codes + +| Name | Description | +| ----------------- | ---------------------------------------- | +| UNKNOWN_KEY | The unknown key | +| BACKSPACE_KEY | The backspace key | +| TAB_KEY | The tab key | +| CLEAR_KEY | The clear key | +| RETURN_KEY | The return key | +| PAUSE_KEY | The pause key | +| ESCAPE_KEY | The escape key | +| SPACE_KEY | The space key | +| EXCLAIM_KEY | The exclaim key | +| DOUBLE_QUOTE_KEY | The double quote key | +| HASH_KEY | The hash key | +| DOLLAR_KEY | The dollar key | +| AMPERSAND_KEY | The ampersand key | +| QUOTE_KEY | The quote key | +| LEFT_PAREN_KEY | The left paren key | +| RIGHT_PAREN_KEY | The right paren key | +| ASTERISK_KEY | The asterisk key | +| PLUS_KEY | The plus key | +| COMMA_KEY | The comma key | +| MINUS_KEY | The minus key | +| PERIOD_KEY | The period key | +| SLASH_KEY | The slash key | +| NUM_0_KEY | The num 0 key | +| NUM_1_KEY | The num 1 key | +| NUM_2_KEY | The num 2 key | +| NUM_3_KEY | The num 3 key | +| NUM_4_KEY | The num 4 key | +| NUM_5_KEY | The num 5 key | +| NUM_6_KEY | The num 6 key | +| NUM_7_KEY | The num 7 key | +| NUM_8_KEY | The num 8 key | +| NUM_9_KEY | The num 9 key | +| COLON_KEY | The colon key | +| SEMI_COLON_KEY | The semi colon key | +| LESS_KEY | The less key | +| EQUALS_KEY | The equals key | +| GREATER_KEY | The greater key | +| QUESTION_KEY | The question key | +| AT_KEY | The at key | +| LEFT_BRACKET_KEY | The left bracket key | +| BACKSLASH_KEY | The backslash key | +| RIGHT_BRACKET_KEY | The right bracket key | +| CARET_KEY | The caret key | +| UNDERSCORE_KEY | The underscore key | +| BACKQUOTE_KEY | The backquote key | +| A_KEY | The A key | +| B_KEY | The B key | +| C_KEY | The C key | +| D_KEY | The D key | +| E_KEY | The E key | +| F_KEY | The F key | +| G_KEY | The G key | +| H_KEY | The H key | +| I_KEY | The I key | +| J_KEY | The J key | +| K_KEY | The K key | +| L_KEY | The L key | +| M_KEY | The M key | +| N_KEY | The N key | +| O_KEY | The O key | +| P_KEY | The P key | +| Q_KEY | The Q key | +| R_KEY | The R key | +| S_KEY | The S key | +| T_KEY | The T key | +| U_KEY | The U key | +| V_KEY | The V key | +| W_KEY | The W key | +| X_KEY | The X key | +| Y_KEY | The Y key | +| Z_KEY | The Z key | +| DELETE_KEY | The delete key | +| KEYPAD_0 | The keypad 0 key | +| KEYPAD_1 | The keypad 1 key | +| KEYPAD_2 | The keypad 2 key | +| KEYPAD_3 | The keypad 3 key | +| KEYPAD_4 | The keypad 4 key | +| KEYPAD_5 | The keypad 5 key | +| KEYPAD_6 | The keypad 6 key | +| KEYPAD_7 | The keypad 7 key | +| KEYPAD_8 | The keypad 8 key | +| KEYPAD_9 | The keypad 9 key | +| KEYPAD_PERIOD | The keypad period key | +| KEYPAD_DIVIDE | The keypad divide key | +| KEYPAD_MULTIPLY | The keypad multiply key | +| KEYPAD_MINUS | The keypad minus key | +| KEYPAD_PLUS | The keypad plus key | +| KEYPAD_ENTER | The keypad enter key | +| KEYPAD_EQUALS | The keypad equals key | +| UP_KEY | The up key | +| DOWN_KEY | The down key | +| RIGHT_KEY | The right key | +| LEFT_KEY | The left key | +| INSERT_KEY | The insert key | +| HOME_KEY | The home key | +| END_KEY | The end key | +| PAGE_UP_KEY | The page up key | +| PAGE_DOWN_KEY | The page down key | +| F1_KEY | The f1 key | +| F2_KEY | The f2 key | +| F3_KEY | The f3 key | +| F4_KEY | The f4 key | +| F5_KEY | The f5 key | +| F6_KEY | The f6 key | +| F7_KEY | The f7 key | +| F8_KEY | The f8 key | +| F9_KEY | The f9 key | +| F10_KEY | The f10 key | +| F11_KEY | The f11 key | +| F12_KEY | The f12 key | +| F13_KEY | The f13 key | +| F14_KEY | The f14 key | +| F15_KEY | The f15 key | +| NUM_LOCK_KEY | The num lock key | +| CAPS_LOCK_KEY | The caps lock key | +| SCROLL_LOCK_KEY | The scroll lock key | +| RIGHT_SHIFT_KEY | The right shift key | +| LEFT_SHIFT_KEY | The left shift key | +| RIGHT_CTRL_KEY | The right control key | +| LEFT_CTRL_KEY | The left control key | +| RIGHT_ALT_KEY | The right alt key | +| LEFT_ALT_KEY | The left alt key | +| LEFT_SUPER_KEY | The left super (windows or command) key | +| RIGHT_SUPER_KEY | The right super (windows or command) key | +| MODE_KEY | The mode key | +| HELP_KEY | The help key | +| SYS_REQ_KEY | The sys req key | +| MENU_KEY | The menu key | +| POWER_KEY | The power key | + +### How key codes are used + +`Key Code` is useful for reading and handling keyboard inputs within SplashKit. There are many +functions that take in `Key Code` as a parameter, such as `Key Down`, `Key Typed`, and `Key Up`. You +may use these functions when creating games that take in inputs from the user's keyboard. There is +also the `Key Name` function that returns the string name of a given `Key Code`. + +## Key Name + +Now that we know how `Key Code` is used, we can implement it on functions such as `Key Name`. + +`Key Name` is one of the functions that use `Key Code` as its input. It returns the string name of a +given `Key Code`. This can be useful to display the key names when configuring game controls, +debugging log, or as feedback to player input. + +### Syntax + +### Example + +In this example, the `Key Name` function is used to print out the name of the key to the screen +using the `draw_text()` function. + +Example in C++: + +``` +int main() +{ + key_code start_button = SPACE_KEY; // Press space to start + + open_window("Game", 800, 600); + + while(!key_down(ESCAPE_KEY)) + { + clear_screen(COLOR_BLACK); + + process_events(); // check keyboard state + + draw_text("Press " + key_name(start_button) + " to start!", COLOR_WHITE, 100, 300); // Display text "Press space to start" + + refresh_screen(60); + } + + return 0; +} +``` diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Publishing with SplashKit - C# b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Publishing with SplashKit - C# new file mode 100644 index 00000000..23728b8a --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Tutorial Markdowns/Publishing with SplashKit - C# @@ -0,0 +1,59 @@ +# Publishing in SplashKit - C# / C++ + +## Sharing created programs + +So let's say you've made something. Congragulations! But, you probably want to be able to send this +to someone for whatever reason without guiding them through a compile instruction process, or the +entire SplashKit install procedure, or send through any individual assets, or any other numbers of +more complicated than just sending a folder methods. + +In previous guides, you might have seen usage of `skm dotnet run` or `skm clang++ program.cpp` to +compile programs, this guide intends to go a little more in-depth as to the nature of publishing and +sharing compiled and published programs. + +Let's take the following code snippet in C# as an example: + +```c# +public class Program +{ + public static void Main() + { //Window Creation + Window baseWindow = new Window("publishing!", 800, 800); + + baseWindow.DrawCircle(Color.Black, 400, 400, 100); + SplashKit.RefreshScreen(); + SplashKit.Delay(2000); + } +} +``` + +You can run the code if interested, but it's just a simple program that opens a window, draws a +SplashKit generated circle, and then quits. What's important about this code snippet is that it has +no external object references, so we're not loading in any files such as bitmaps, or audio or +animation files, or anything else SplashKit might let us use. + +If you were to run `skm dotnet publish`, a folder would be created in the directory of the +accompanying source code called `bin`, and then a further folder called `debug` holds our created +`program.exe` file. It's safest to share the entire debug folder, especially in reference to the +upcoming behavior and section of the guide. + +## Sharing created programs with assets + +Now if you were to copy the above steps, but in a piece of code that does explicitly reference +object pointers that get read in by SplashKit for local files, such as Bitmap instantiations, you +would see a lot of errors pop up in the console accompanying your `program.exe` saying something +akin to: + +``` +Unable to locate file for {sprite} ({filepath}) +``` + +Where sprite and filepath would be your locally referenced bitmap and filepath respectively. What's +important to know is that SplashKit doesn't transfer over these resources during the publishing +process. In order to remedy this as an example, just copy over your `images` folder that we +described in an earlier guide (that would house all of your bitmaps for instantiation) into the +debug/netx.0 folder manually. + +This trend runs true for both C# and C++, compiling and publishing via `skm dotnet publish` for C# +and `skm clang++ program.cpp -o program.exe` will both require manual copying of any imported assets +into the shared root folder of an associated .exe file. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Understanding SplashKit Manager (SKM) Shell Commands.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Understanding SplashKit Manager (SKM) Shell Commands.md new file mode 100644 index 00000000..9cf7f7ae --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/Understanding SplashKit Manager (SKM) Shell Commands.md @@ -0,0 +1,82 @@ +## Title: Understanding SplashKit Manager (SKM) Shell Commands + +### Introduction + +This tutorial aims to provide a comprehensive understanding of the SplashKit Manager (SKM) shell +commands. SKM is a powerful command-line tool used for managing SplashKit projects and resources. By +the end of this tutorial, you will have a solid grasp of each SKM command, enabling you to +efficiently work with SplashKit projects and streamline your development process. + +### Prerequisites + +To make the most of this tutorial, you should have basic knowledge of programming and familiarity +with the command line. Prior experience with C++, Python, or Pascal will be beneficial but not +mandatory. + +### Functions Used + +1. `clang++` +1. `dotnet` +1. `fix` +1. `fpc` +1. `g++` +1. `help` +1. `linux` +1. `new` +1. `python3` +1. `resources` +1. `revert` +1. `uninstall` +1. `update` + +### Table of Contents + +1. **Introduction to SKM** + + - What is SplashKit Manager (SKM)? + - Installation and setup + +1. **Working with SKM Commands** + + - Overview of the SKM command structure + - Basic usage: `skm [command] [arguments]` + +1. **Understanding SKM Commands** + + - Detailed explanation of each command + - Examples of command usage + - Common use cases for each command + +1. **Integration with IDEs and build systems** + - Integrating SKM with IDEs and build systems + +### Tutorial Details + +This tutorial will be presented as a step-by-step guide with hands-on examples for each SKM command. +The tutorial will be suitable for intermediate-level programmers interested in game development and +working with the SplashKit library. Each command will be explained in a clear, concise manner, with +practical demonstrations to ensure a deep understanding of its functionality. + +### Expected Learning Outcomes + +After completing this tutorial, you will be able to: + +1. Install and set up SplashKit Manager (SKM) for your projects. +1. Execute various SKM commands and understand their purposes. +1. Compile and run SplashKit projects using different compilers (`clang++`, `g++`, `fpc`, `dotnet`, + `python3`). +1. Create new SplashKit projects and manage project resources. +1. Fix common path-related issues in SplashKit projects. +1. Upgrade or revert to different versions of SplashKit as needed. +1. Uninstall SKM when necessary. + +### Conclusion + +Upon completing the tutorial, readers will be equipped with the knowledge and skills to install and +set up SKM for their projects, execute different SKM commands, work with various compilers (e.g., +clang++, g++, fpc, dotnet, python3), create new SplashKit projects, manage project resources, +resolve path-related issues, update or revert to different versions of SplashKit, and uninstall SKM +when required. + +With this expertise, developers can streamline their workflow, leverage the full potential of +SplashKit, and efficiently create engaging and interactive projects. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/2023-07-30-using-keycallbacks.html.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/2023-07-30-using-keycallbacks.html.md new file mode 100644 index 00000000..e8dc75fb --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/2023-07-30-using-keycallbacks.html.md @@ -0,0 +1,171 @@ +--- +title: Using Key Callbacks +date: 2023-07-30 06:21 UTC +author: Ro +author_url: +tags: input +summary: | + Key Callbacks provide a method to indirectly run commands based on detected key events. + Instead of directly checking the state of a key press, process event will run the callback function + when it detects the event depending on the type it has been registered for. +related_funcs: + - register_callback_on_key_down + - register_callback_on_key_typed + - register_callback_on_key_up + - deregister_callback_on_key_down + - deregister_callback_on_key_typed + - deregister_callback_on_key_up +--- + +Key Callbacks are essentially function calls for when process event function detects any of the +three types of events. Using this object, we can avoid directly checking for key states every frame +ourselves. + +These are the three event types that are available for callback + +| Name | Trigger | +| ----- | -------------- | +| Down | Key is held | +| Typed | On key press | +| Up | On key release | + +Note that down has a small pause before continuous calling. Multiple held keys do not increase rate. +Depending on keyboard N-key rollover, it may also stop when a set of keys held, some are released. + +## Creating A Callback Function + +To start using key callbacks, we need a function that has the structure the object is expecting. + +This entails a single integer parameter and a void return type. + +```c# + + public void KeyEvent(int code) + { + // your code here + } + +``` + +## Selecting A Key + +The function when registered will run regardless of which key initiated the event. So it is +necessary to check what key the callback refers to, if your code is to change its behaviour based on +the key given. + +The integer "code" argument represents the key that triggered the event, and can be type casted into +KeyCode for direct comparisons to specific keys. + +```c# + + public void KeyEvent(int code) + { + if ((KeyCode)code == KeyCode.AKey) + { + // your code if A key here + } + } + +``` + +Alternatively, you can utilize collection objects to dynamically check if an entry exists for a +given code. In this C# example, a dictionary object is used as it cannot have entries with identical +keys and has try functions, that automatically retrieve the value into a variable while returning a +boolean if it was successful. + +```c# + + private Dictionary dict = new Dictionary + { + {114, Color.Red}, // 114 = R + {103, Color.Green}, // 103 = G + {98, Color.Blue} // 98 = B + }; + private Color clr; + + public void KeyEvent(int code) + { + + if (!dict.TryGetValue(code, out clr)) // clr will receive a default value, if code isn't found + { + clr = Color.White; // instead of default value, we change it to this + } + } + +``` + +The KeyCode enumerable can be used instead for the dictionary keys, and can help limit the key value +pairs. + +## Declaring And Initialising A KeyCallback object + +Once you have a function to be used for callbacks, a KeyCallback object is needed to refer to the +function and be registered for process event to be aware of. + +```c# + +public KeyCallback kcb; + +kcb = new KeyCallback(KeyEvent); // put the name of your function inside + +``` + +## Registering a Key Callback Object + +With an initialised Key Callback object, we need to register it for process event to use it. + +```c# + +Splashkit.RegisterCallbackOnKeyTyped(kcb); // call on press + +Splashkit.RegisterCallbackOnKeyDown(kcb); // call on hold + +Splashkit.registerCallbackOnKeyUp(kcb); // call on lift + +``` + +The above example, will start running the function kcb contains. The event typed specifies when any +key is initially pressed down, as shown in the table above. + +While you can register the same object for all three events, doing so may be at odds with its +design. As normally you would want different behaviours based on the different events. + +## Deregistering a Key Callback object + +When you want a callback to stop being called by process event, you need to run the deregister +function to do so. + +```c# + +Splashkit.DeregisterCallbackOnKeyTyped(kcb); // stop calling on press + +Splashkit.DeregisterCallbackOnKeyDown(kcb); // stop calling on hold + +Splashkit.DeregisterCallbackOnKeyUp(kcb); // stop calling on lift + +``` + +If you did register it for multiple event types, you need to run it for each type as well to +completely remove it from being called. + +Such examples of when this is necessary is if you were to switch between menus that have their own +behaviours. + +Deregister is important if you implement Key Callbacks in classes that are disposed of. As process +event will throw an error trying to reach the callback. + +## C# Demonstration Program + +A Splashkit Demo of Key Callbacks is available here LINK IT + +The code showcases the process event running the callback functions by displaying the last key +detected with its related integer code. The Down and Up callbacks are linked to a incrementing +counter based on how many callbacks for Down Event receive before any key is released. + +## Storing Key Codes outside of program + +If you want to store a keycode in JSON, an integer is recommended. Strings can still be used to +compare, but need extra work to be converted back into Key codes, since there isn't a Splashkit +function to convert string into key code, only from key code into string. + +A table to lookup the numeric value of a key can be found here LINK IT diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.deps.json b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.deps.json new file mode 100644 index 00000000..1ea709f4 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.deps.json @@ -0,0 +1,23 @@ +{ + "runtimeTarget": { + "name": ".NETCoreApp,Version=v6.0", + "signature": "" + }, + "compilationOptions": {}, + "targets": { + ".NETCoreApp,Version=v6.0": { + "KCB_test/1.0.0": { + "runtime": { + "KCB_test.dll": {} + } + } + } + }, + "libraries": { + "KCB_test/1.0.0": { + "type": "project", + "serviceable": false, + "sha512": "" + } + } +} \ No newline at end of file diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.dll b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.dll new file mode 100644 index 00000000..46e64595 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.dll differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.exe b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.exe new file mode 100644 index 00000000..a462fa87 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.exe differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.pdb b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.pdb new file mode 100644 index 00000000..92b42e49 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.pdb differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.runtimeconfig.json b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.runtimeconfig.json new file mode 100644 index 00000000..4986d16e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/KCB_test.runtimeconfig.json @@ -0,0 +1,9 @@ +{ + "runtimeOptions": { + "tfm": "net6.0", + "framework": { + "name": "Microsoft.NETCore.App", + "version": "6.0.0" + } + } +} \ No newline at end of file diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/pdark.ttf b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/pdark.ttf new file mode 100644 index 00000000..0eace6ef Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/pdark.ttf differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/pricedown_bl.otf b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/pricedown_bl.otf new file mode 100644 index 00000000..f06a2bee Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/pricedown_bl.otf differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/readme.txt b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/readme.txt new file mode 100644 index 00000000..18d42aac --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/readme.txt @@ -0,0 +1 @@ +You can place fonts in this folder. Fonts can be otf or ttf files. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/typodermic-eula-03-2020.pdf b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/typodermic-eula-03-2020.pdf new file mode 100644 index 00000000..845ff962 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo exe/Resources/fonts/typodermic-eula-03-2020.pdf differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Program.cs b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Program.cs new file mode 100644 index 00000000..68fffbc6 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Program.cs @@ -0,0 +1,116 @@ +using System; +using SplashKitSDK; + + +// demonstration code for KeyCallback object +// +namespace KCB_test +{ + public class Program + { + private static KeyCallback kcb_Typed; // declare key callback object + private static KeyCallback kcb_Down; + private static KeyCallback kcb_Up; + private static String kcb_Typed_Keyname; // string object to hold the string name + private static int kcb_Typed_Code; + private static int kcb_Down_Held = 0; + private static Color textClr; + + // store colors related to keycode in dictionary object + private static Dictionary kcb_Color = new Dictionary + { + {114, Color.Red}, // 114 = R + {103, Color.Green}, // 103 = G + {98, Color.Blue} // 98 = B + }; + + private static Dictionary kcb_Up_Act = new Dictionary + { + {100, () => logging("sample text")} // 100 = D + }; + + + public static void Main() + { + Window programWindow = SplashKit.OpenWindow("KeyCallbacks", 640, 480); + Font f = new Font("pricedown_bl", "pricedown_bl.otf"); + + + // key callback initialized with function name + kcb_Typed = new KeyCallback(KeyEventTyped); // press + kcb_Down = new KeyCallback(KeyEventDown); // held + kcb_Up = new KeyCallback(KeyEventUp); // depress + + + kcb_Typed_Keyname = "N/A"; + textClr = Color.White; + + SplashKit.RegisterCallbackOnKeyTyped(kcb_Typed); // key callback is added to list to be called by process events + SplashKit.RegisterCallbackOnKeyDown(kcb_Down); + SplashKit.RegisterCallbackOnKeyUp(kcb_Up); + + while (!programWindow.CloseRequested) + { + SplashKit.ProcessEvents(); + + programWindow.Clear(Color.Black); + + programWindow.DrawText(kcb_Typed_Keyname, textClr, f, 40, 200, 200); // display the text name of the code from callback + programWindow.DrawText(kcb_Typed_Code.ToString(), textClr, f, 40, 200, 260); // display the code from callback + programWindow.DrawText("Held: " + kcb_Down_Held, textClr, f, 40, 200, 320); // display the callbacks from hold + + programWindow.Refresh(60); + } + + SplashKit.DeregisterCallbackOnKeyTyped(kcb_Typed); + SplashKit.DeregisterCallbackOnKeyDown(kcb_Down); + SplashKit.DeregisterCallbackOnKeyUp(kcb_Up); + // remove key callback from being called, not important here + // but if the object is located in an object that is disposed of + // it can throw an error + + programWindow.Close(); + } + + private static void KeyEventTyped(int code) // key pressed + { + kcb_Typed_Keyname = SplashKit.KeyName((KeyCode)code); + kcb_Typed_Code = code; + + // A dictionary can be used to avoid hardcoded specific code checks + // instead if the key exists in the dictionary, it will extract the value + if (!kcb_Color.TryGetValue(code, out textClr)) + { + textClr = Color.White; // if not found, set to white + } + + if (KeyCode.XKey == (KeyCode)code) // check if X key was pressed + { + // insert your code here + } + } + + private static void KeyEventDown(int code) // key held + { + kcb_Down_Held++; + } + + private static void KeyEventUp(int code) // key depressed + { + kcb_Down_Held = 0; + + Action a; + if (kcb_Up_Act.TryGetValue(code, out a)) // using an action, to retrieve code to run from dictionary + { + a(); + } + } + + private static void logging(String text) + { + Console.Out.WriteLine(text); + } + + + } +} diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/pdark.ttf b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/pdark.ttf new file mode 100644 index 00000000..0eace6ef Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/pdark.ttf differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/pricedown_bl.otf b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/pricedown_bl.otf new file mode 100644 index 00000000..f06a2bee Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/pricedown_bl.otf differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/readme.txt b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/readme.txt new file mode 100644 index 00000000..18d42aac --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/readme.txt @@ -0,0 +1 @@ +You can place fonts in this folder. Fonts can be otf or ttf files. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/typodermic-eula-03-2020.pdf b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/typodermic-eula-03-2020.pdf new file mode 100644 index 00000000..845ff962 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/kcb/kcb demo src/Resources/fonts/typodermic-eula-03-2020.pdf differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/2023-08-04-using-spriteeventhandler.md b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/2023-08-04-using-spriteeventhandler.md new file mode 100644 index 00000000..930b8e22 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/2023-08-04-using-spriteeventhandler.md @@ -0,0 +1,305 @@ +--- +title: Using Sprite Event Handlers +date: 2023-08-04 06:43 UTC +author: Ro +tags: sprites +summary: | + Sprite Event Handlers are callbacks for sprites. Splashkit provides a limited number of + Events to be listened for. +related_funcs: + - sprite_call_on_event + - sprite_stop_calling_on_event +--- + +# Sprite Event Handlers + +Sprite Event Handlers are objects that contain a function to be called when Splashkit detects any of +the following events + +| Name | Trigger | +| ---------- | -------------------------------------------------------------- | +| Arrived | Move_To with duration overload finished | +| Anim Ended | Frame Animation has reached last cell with no Next frame | +| Touched | CURRENTLY COMMENTED OUT IN SOURCE, Clicked + 17 pixels away | +| Clicked | Mouse Left clicked, and within 1 pixel radius of sprite pixels | + +The more useful events are animation ended and clicked. + +#### Arrived Event + +Arrived only occurs when a Move_To function is called on the sprite with a duration overload which +tells it how many seconds to reach the new point. The current implementation of it will jump +positions every frame instead of smoothly moving like dX dY/ Velocity based movement. + +#### Touched Event + +Touched is as noted in the table, has currently been commented out of the source code, so it never +happens. Both it and clicked utilize the same conditions, but touched will use a larger radius +circle to check if it is in contact with a given sprite. + +#### Animation Ended Event + +Animation Ended is useful, if you want to code behaviour to happen at the end of a specific frame. +Anim scripts have movement vectors and link audio files to a given frame, but if you wish to check +for collisions at a specific frame end, you can set up an event handler to tell you when to do so. +**NOTE if you want this event to occur, the animation script must use frames with an empty NEXT +value, otherwise it won't recognise it ending**, thus self-looping scripted frames don't work with +this, to compensate you require the event to continue the looping. + +#### Clicked Event + +Clicked is self-explanatory, if the mouse left clicks on the window, Splashkit will check the point +being within 1 pixel radius away from any registered sprite. This could be used to make UI elements +for mouse, but the right click does not trigger this event. So using the input section of mouse +functions may still be better, as they have an expanded range of functions. If multiple sprites are +under the mouse, the event will be triggered for all registered sprites. + +## Creating A Sprite Event Handler Fucntion + +Sprite Event Handlers require a function for initialisation. This is used for Splashkit to call, +when a sprite has been registered to the event handler object. + +The function has two parameters, a Integer Pointer and a Integer + +```c# + + public void SpriteEventHandlerFunction(IntPtr pointer, Int event) + { + // your code here + } + +``` + +## Integer Pointer in C# Limitation + +Integer Pointer is the pointer of the sprite that is linked to the event called. In C# its +usefulness is diminished As you cannot convert it back to the sprite object, you can only compare it +to the original variable. + +```c# + +IntPtr pointer; +Sprite spriteObject; + +if (pointer == spriteObject) // check sprite has same pointer value as pointer in callback +{ + // run if matching +} + +``` + +**THIS SECTIONS NEEDS VERIFICATION IN C++ CODE, AND MAYBE REWRITTEN** + +C++ does not have this limitation and can revert the pointer back to its sprite pointer form + +```c++ + +Sprite* spr = (Sprite*)pointer.ToPointer(); // convert IntPtr back to sprite pointer + +``` + +## Checking the Event type + +Splashkit will not limit the callback to any select event, so the function needs to filter the +integer argument to determine which event callback was for. + +```c# + + public void SpriteEventHandlerFunction(IntPtr pointer, Int event) + { + if ((SpriteEventKind) ev == SpriteEventKind.SpriteArrivedEvent) // 0 + { + // Move_To function finished + } + else if ((SpriteEventKind) ev == SpriteEventKind.SpriteAnimationEndedEvent) // 1 + { + // Animation frame has no NEXT set + } + else if ((SpriteEventKind) ev == SpriteEventKind.SpriteTouchedEvent) // 2 + { + // SRC COMMENTED OUT, Clicked + 17 pixel range + } + else if ((SpriteEventKind) ev == SpriteEventKind.SpriteClickedEvent) // 3 + { + // Mouse left click, check point for sprite collision. + } + } + +``` + +## Declaring and Initialising A Sprite Event Handler Object + +A Sprite Event Handler needs to be declared somewhere, then initialised to be ready for registering +for an accompanying Sprite. + +Be careful where you declare it, as it needs to avoid being disposed otherwise it will throw errors +by having been disposed of. + +```c# + + SpriteEventHandler SEH; // Declare + + SEH = new SpriteEventHandler(SpriteEventHandlerFunction); // Initialise + +``` + +There shouldn't be a need to have multiple Sprite Event Handlers for a single function. As multiple +sprites can be registered for a single Sprite Event Handler, thus called for the same function. + +## Registering A Sprite and Event Handler + +With a initialised Sprite Event Handler, we can start registering sprites to call the function, when +a listed event occurs to them. + +```c# + + SplashKit.SpriteCallOnEvent(SpriteA,SEH); // Register Sprite for an Event handler + +``` + +Now when the listed event triggers above occur, the given sprite will call the function. + +## Registering Multiple Sprite Event Handlers to one Sprite + +This is an option if you want to selectively enable different behaviours by making it run a set of +functions for the events. + +```c# + + SplashKit.SpriteCallOnEvent(SpriteA,SEH1); + SplashKit.SpriteCallOnEvent(SpriteA,SEH2); + SplashKit.SpriteCallOnEvent(SpriteA,SEH3); + +``` + +The multiple event handlers can use different functions to be called. This could help in avoiding +monolithic blocks in a singular event handler. + +Alternatively you could register them at different stages of the sprite's state. + +## Deregistering Sprite Event Handlers + +Splashkit needs to be updated to stop calling a Sprite Event Handler when it no longer exists, +otherwise it will cause errors when a sprite continues have events occur. + +```c# + +Splashkit.SpriteStopCallingOnEvent(SpriteA,SEH); // Stop sprite from calling Event Handler + +``` + +Classes containing a Sprite Event Handler, should implement a dispose function to do this. + +## Sprite and Sprite Event Handler Container + +Since in C# we need to find the sprite matching the pointer, this causes some added complexity to +handle it. + +As a attempt to bypass the need to match the pointer to its sprite, you can create an class that +holds a Sprite and Sprite Event Handler, then create a function to directly access the sprite in the +class. + +```c# + +public class SpriteEventHandlerContainer : IDisposable +{ + public Sprite spr; + private SpriteEventHandler seh; + + public SpriteEventContainer(Sprite spr) + { + this.spr = spr; + seh = new SpriteEventHandler(Callback); // initialise with function to call + SplashKit.SpriteCallOnEvent(spr, seh); // add to splashkit to start checking sprite + } + + private void Callback(IntPtr ptr, int ev) + { + // code specific to the sprite contained in this class. + } + + // stop calling events on disposal + public void Dispose() + { + SplashKit.SpriteStopCallingOnEvent(spr, seh); + } + +} + +``` + +This is only a suggestion on how to handle selecting the originating sprite for callback functions. + +It may also work better as an child class of Sprite. + +## Animation Ended Events + +As detailed above, the event animation ended, only occurs when the frame has no NEXT set to it. A +self-looping set will never trigger it. + +``` + +f: [0-8], [0-8], 10, 1 + +``` + +If you want to trigger it at the end of the frame set, you can remove the NEXT value. But the +program then needs to handle restarting the animation if you still want it to self-loop. This can be +handled by using the animation event ended. + +``` + +f: [0-8], [0-8], 10, + +``` + +Now the animation will trigger it when finished. + +```c# +// HANDLE SPRITE ORIGINATOR OF CALLBACK +if ((SpriteEventKind) ev == SpriteEventKind.SpriteAnimationEndedEvent) // 1 + { + // Check which animation finished + // Determine what to do based on it + sprite.StartAnimation(ANIM_NAME); // line to start next animation + } + +``` + +The above code is a simple example of starting another animation when the event is triggered. +Doesn't detail origin sprite selection or changing behaviour on which animation finished. + +If you want the event to trigger in between the animations, it can be done by splitting the set into +two. + +``` + +f: [0-3], [0-3], 10, +f: [4-8], [4-8], 10, 1 // remove NEXT if you want the event to happen at end too. + +``` + +With this, the event will trigger on finishing the 4th frame of the overall animation. It still +needs code to continue into the 2nd part of the original animation set. + +## C# Demonstration Program + +A Splashkit Demo of Sprite Event Handler is available here **_LINK IT_** + +Most of the information is found in the code commentation and console log of the application + +One sprite, demonstrates the move to event with a given duration. The other two circles are static, +and have different callback functions. + +All the sprites will console log in their callback function, so all of them can demonstrate the +clicked event. However two specific sprites will outline a red rectangle to directly show them +having been "selected" by being the last clicked sprite, using the first event handler. The other +two won't as their callback function differs. + +Animation ended event is utilized by the bottom-most sprite, based on code from a splashkit game. It +runs a exploding animation on pressing U, which starts the animation from the main loop. This +exploding animation is composed of two frame sets, and is coded to start the 2nd part on detecting +the 1st part has finished. If you want to insert functions (i.e collision detection, state changes) +that happen at certain points of an animation you could utilize this example as a possible method. + +As this is a C# program, it does not have an example of converting IntPtr into a sprite pointer. diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/Resources/animations/RockLarge.txt b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/Resources/animations/RockLarge.txt new file mode 100644 index 00000000..df8e44f5 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/Resources/animations/RockLarge.txt @@ -0,0 +1,13 @@ +SplashKit Animation + +// ID, Cell Number, Frame Time, Next Frame + +// normal +f: 0,0,1,0 +// explode +f: [1-4], [1-4], 5, +f: [5-8], [5-8], 5, + +i:normal,0 +i:explode,1 +i:explode2,5 diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/Resources/images/RockLarge.png b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/Resources/images/RockLarge.png new file mode 100644 index 00000000..e2400e0c Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/Resources/images/RockLarge.png differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.deps.json b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.deps.json new file mode 100644 index 00000000..bfb3dd0a --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.deps.json @@ -0,0 +1,23 @@ +{ + "runtimeTarget": { + "name": ".NETCoreApp,Version=v6.0", + "signature": "" + }, + "compilationOptions": {}, + "targets": { + ".NETCoreApp,Version=v6.0": { + "SEH_test/1.0.0": { + "runtime": { + "SEH_test.dll": {} + } + } + } + }, + "libraries": { + "SEH_test/1.0.0": { + "type": "project", + "serviceable": false, + "sha512": "" + } + } +} \ No newline at end of file diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.dll b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.dll new file mode 100644 index 00000000..4e84e2a2 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.dll differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.exe b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.exe new file mode 100644 index 00000000..e0fa9849 Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.exe differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.pdb b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.pdb new file mode 100644 index 00000000..926ac81d Binary files /dev/null and b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.pdb differ diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.runtimeconfig.json b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.runtimeconfig.json new file mode 100644 index 00000000..4986d16e --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/SEH_test.runtimeconfig.json @@ -0,0 +1,9 @@ +{ + "runtimeOptions": { + "tfm": "net6.0", + "framework": { + "name": "Microsoft.NETCore.App", + "version": "6.0.0" + } + } +} \ No newline at end of file diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/myeasylog.log b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo/myeasylog.log new file mode 100644 index 00000000..e69de29b diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo_src/Program.cs b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo_src/Program.cs new file mode 100644 index 00000000..fd9bf420 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo_src/Program.cs @@ -0,0 +1,131 @@ +using System; +using SplashKitSDK; + +namespace SEH_test +{ + public class Program + { + private static SpriteEventHandler SprEveHand1, SprEveHand2; // + private static List sprs; // used as total collection of sprites + private static Sprite selectedSpr; // used by clicked event to refer to last clicked sprite + private static SpriteEventContainer sec; // class to pair a event handler to a sprite without having to compare pointers + + + public static void Main() + { + Window programWindow = SplashKit.OpenWindow("KeyCallbacks", 640, 480); + //Font f = new Font("pricedown_bl", "pricedown_bl.otf"); + + initProgram(); + + while (!programWindow.CloseRequested) + { + SplashKit.ProcessEvents(); + + programWindow.Clear(Color.Black); + + SplashKit.UpdateAllSprites(); + SplashKit.DrawAllSprites(); + + if (selectedSpr != null) // only sprites with event handler 1 on call, last clicked, draw its boundary + { + programWindow.DrawRectangle(Color.Red,selectedSpr.CollisionRectangle); + } + // only objects running SprEventHandler function on call will be able to be selected for this + + if (SplashKit.KeyTyped(KeyCode.UKey)) // start animation key for anim event test sprite event handler + { + sec.spr.StartAnimation("explode"); + } + + programWindow.Refresh(60); + } + + programWindow.Close(); + } + + private static void initProgram() + { + sprs = new List(); + Bitmap b = new Bitmap("circle", 50,50); + + + + b.FillCircle(Color.White, 25,25,24.99); + sprs.Add(new Sprite(b)); + sprs.Add(new Sprite(b)); + sprs.Add(new Sprite(b)); + + sprs[0].X = 100; + sprs[0].Y = 100; + + sprs[1].X = 50; + sprs[1].Y = 50; + sprs[1].MoveTo(new Point2D{X=300,Y=50},3); // test for sprite arrived event, overload without time taken does not call event + + sprs[2].X = 200; + sprs[2].Y = 200; + + Bitmap ast = new Bitmap("Rock", "RockLarge.png"); // anim test event bitmap + ast.SetCellDetails(200,200,3,3,9); + + SprEveHand1 = new SpriteEventHandler(SprEventHandler); // initialise, with function we want to call + SprEveHand2 = new SpriteEventHandler(SprEventHandler2); // will run different function than above + + // the sprite has to be added to the list to called when an specified event happens to it + // when an event happens, it will call the function in the event handler + SplashKit.SpriteCallOnEvent(sprs[0],SprEveHand1); + SplashKit.SpriteCallOnEvent(sprs[1],SprEveHand1); + SplashKit.SpriteCallOnEvent(sprs[2],SprEveHand2); // using a different event handler, with different function + + // class holding a sprite and a event handler, called function does not need to match sprite pointers in this way + sec = new SpriteEventContainer(new Sprite(ast, SplashKit.LoadAnimationScript("Rock","RockLarge.txt"))); + sec.spr.MoveTo(300,300); + sec.spr.StartAnimation("normal"); + + } + + private static void SprEventHandler(IntPtr ptr, int ev) + { + + Console.Out.WriteLine("SPRITE: " + ptr + " EVENT: " + ev); + + if ((SpriteEventKind) ev == SpriteEventKind.SpriteArrivedEvent) // 0 + { + // Using a move function on the sprite, when it finishes the move, this event will trigger + } + else if ((SpriteEventKind) ev == SpriteEventKind.SpriteAnimationEndedEvent) // 1 + { + // Sprite has ended a animation + // Triggers when Animation Frame has no NEXT value. + } + else if ((SpriteEventKind) ev == SpriteEventKind.SpriteTouchedEvent) // 2 + { + // THIS EVENT IS CURRENTLY COMMENTED OUT IN THE SOURCE CODE + // Splashkit and Swingame conditions are Clicked Event but with 17p radius check from mouse instead + } + else if ((SpriteEventKind) ev == SpriteEventKind.SpriteClickedEvent) // 3 + { + // Mouse was clicked within 1p distance of the sprite's bitmap (excluding empty pixels) + // no setup on the mouse's end is needed, only setting up the sprite event handler + // could be used for UI buttons using sprites. + + // important for C#, as it is very difficult to convert the pointer back to an object + for (int i = 0; i < sprs.Count; i++) // one method of matching pointers, if event handler is implemented at a level where it is used by many + { + if (sprs[i] == ptr) // match pointer value + { + selectedSpr = sprs[i]; // set this variable to the sprite that matched + } + } + } + + } + + private static void SprEventHandler2(IntPtr ptr, int ev) // seperate function, to show that different functions can be used for sprites if you want + { + Console.Out.WriteLine("SPRITE: " + ptr + " I want you to do something different"); + } + + } +} diff --git a/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo_src/SpriteEventContainer.cs b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo_src/SpriteEventContainer.cs new file mode 100644 index 00000000..cd16b604 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/Tutorials and Research/Tutorial Proposals/seh/seh_demo_src/SpriteEventContainer.cs @@ -0,0 +1,49 @@ +using System; +using SplashKitSDK; + +// class that bundles a event handler with sprite together +// purpose is to avoid needing to match pointer to a specific object +// so this runs a 1-1 relationship so you can directly access the sprite from the called function +public class SpriteEventContainer : IDisposable +{ + public Sprite spr; // sprite concerning the event handler + private SpriteEventHandler seh; // single event handler for sprite + + public SpriteEventContainer(Sprite spr) + { + this.spr = spr; + seh = new SpriteEventHandler(sprCallback); // initialise with function to call + SplashKit.SpriteCallOnEvent(spr, seh); // add to splashkit to start checking sprite + } + + // in this test code, we're hard coding this behaviour for a rock bitmap from asteroids + private void sprCallback(IntPtr ptr, int ev) + { + Console.Out.WriteLine("SPRITE: " + ptr + " EVENT: " + ev); + + if ((SpriteEventKind) ev == SpriteEventKind.SpriteAnimationEndedEvent) // in the test program, we start an animation by U key + { + if (spr.AnimationName() == "explode") // first explode animation frame is done + { + spr.StartAnimation("explode2"); // start 2nd animation frame + Console.Out.WriteLine("FIRST STAGE OF EXPLODE DONE"); + // write other functions here i.e movement layering etc, In Asteroids 3 rocks are spawned here, inbetween the animation + } + else if (spr.AnimationName() == "explode2") // second explode animation frame is done + { + spr.StartAnimation("normal"); // return to normal cell, in Asteroids the object is disposed of here, to finish removing it from game + Console.Out.WriteLine("SECOND STAGE OF EXPLODE DONE"); + // write other functions i.e dispose of objects, set flags etc. + } + } + + } + + public virtual void Dispose() // event handler needs to be disposed, before this object is disposed + { + SplashKit.SpriteStopCallingOnEvent(spr, seh); + spr.Dispose(); // probably not necessary, since it already extends IDisposable + } + + +} \ No newline at end of file diff --git a/src/content/docs/Splashkit/Applications/mingw-automated installation/readme.md b/src/content/docs/Splashkit/Applications/mingw-automated installation/readme.md new file mode 100644 index 00000000..8f0e2d81 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/mingw-automated installation/readme.md @@ -0,0 +1,52 @@ +# Installation Script Documentation + +## Purpose + +This script automates the installation process for SplashKit, .net, C++ tools, and Visual Studio +Code (VS Code) on Windows systems using MSYS2. It ensures a seamless setup of development tools +required for software development. + +## Script Details + +The script is divided into several sections, each responsible for a specific task: + +1. **Update package databases:** Ensures that package databases are up to date before proceeding + with installations. +2. **Install required packages:** Installs necessary packages such as git, curl, and unzip. +3. **Install C++ tools:** Installs essential C++ development tools using `pacman`. +4. **Install .net SDK:** Downloads and installs the .net SDK using PowerShell to handle the + installation process. +5. **Install VS Code:** Downloads and installs VS Code using PowerShell to handle the installation + process. +6. **Install SplashKit:** Downloads and installs SplashKit using the provided installation script. +7. **Install VS Code extensions:** Installs essential VS Code extensions for C++ and .net + development. + +## Usage + +To use the script, follow these steps: + +1. Ensure that you have MSYS2 installed on your system. +2. Copy the script to your system or download it. Save it as `install.sh` inside your MSYS2 home + directory (`C:/msys64/home/{username}/install.sh`). +3. Open a MINGW64 bash terminal window. +4. Go to the directory containing the script: + ```shell + cd ~ + ``` +5. Run the script using the command: + ```shell + bash install.sh + ``` +6. Follow the on-screen prompts and instructions to complete the installation process. +7. After installation, restart your terminal for the changes to take effect. + +## Troubleshooting + +If you encounter any issues during the installation process, consider the following troubleshooting +steps: + +- Check your internet connection to ensure that downloads are not being interrupted. +- Verify that you have the necessary permissions to execute the script. +- Ensure that your system meets the minimum requirements for running the installed tools. +- Refer to the documentation of individual tools for troubleshooting specific issues. diff --git a/src/content/docs/Splashkit/Applications/mingw-automated installation/splashkit-automated-installation-msys2.sh b/src/content/docs/Splashkit/Applications/mingw-automated installation/splashkit-automated-installation-msys2.sh new file mode 100644 index 00000000..51b1c789 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/mingw-automated installation/splashkit-automated-installation-msys2.sh @@ -0,0 +1,85 @@ +#!/bin/bash + +# Define variables +splashkit_url="https://raw.githubusercontent.com/splashkit/skm/master/install-scripts/skm-install.sh" +dotnet_sdk_url="https://download.visualstudio.microsoft.com/download/pr/90486d8a-fb5a-41be-bfe4-ad292c06153f/6673965085e00f5b305bbaa0b931cc96/dotnet-sdk-8.0.300-win-x64.exe" +vscode_installer_url="https://aka.ms/win32-x64-user-stable" + +# Update package databases +echo "Updating package databases..." +pacman -Syy + +# Install required packages +echo "Installing required packages..." +pacman -S --needed --noconfirm git curl unzip + +# Install C++ tools (before SplashKit) +echo "Installing C++ tools..." +pacman -S --needed --noconfirm mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-make mingw-w64-x86_64-toolchain + +# Check if .NET SDK is installed +if ! command -v dotnet &> /dev/null +then + echo "Downloading .NET SDK installer..." + curl -L $dotnet_sdk_url -o dotnet-sdk-installer.exe + + echo "Installing .NET SDK..." + powershell.exe -Command "Start-Process dotnet-sdk-installer.exe -ArgumentList '/quiet /norestart' -Wait" + if [ $? -ne 0 ]; then + echo ".NET SDK installation failed. Please try installing it manually." + exit 1 + fi + + if ! command -v dotnet &> /dev/null + then + echo ".NET SDK installation failed or .NET SDK is not in the PATH. Please check the installation and try again." + exit 1 + fi +else + echo ".NET SDK is already installed." +fi + +# Check if VS Code is installed +if ! command -v code &> /dev/null +then + echo "Downloading Visual Studio Code installer..." + curl -L $vscode_installer_url -o vscode-installer.exe + + echo "Installing Visual Studio Code..." + powershell.exe -Command "Start-Process vscode-installer.exe -ArgumentList '/silent /mergetasks=!runcode' -Wait" + if [ $? -ne 0 ]; then + echo "Visual Studio Code installation failed. Please try installing it manually." + exit 1 + fi + + if ! command -v code &> /dev/null + then + echo "Visual Studio Code installation failed or VS Code is not in the PATH. Please check the installation and try again." + exit 1 + fi +else + echo "Visual Studio Code is already installed." +fi + +# Install SplashKit +echo "Installing SplashKit..." +bash <(curl -s $splashkit_url) +echo 'export PATH=$PATH:~/.splashkit' >> ~/.bashrc +export PATH=$PATH:~/.splashkit +if [ -d ~/.splashkit/global ]; then + echo "Installing SplashKit global" + skm global install +fi + +# Add .NET environment variables +echo 'export DOTNET_ROOT=$HOME/.dotnet' >> ~/.bashrc +echo 'export PATH=$PATH:$HOME/.dotnet' >> ~/.bashrc + +# Install VS Code extensions +echo "Installing VS Code extensions..." +code --install-extension ms-vscode.cpptools-extension-pack +code --install-extension ms-dotnettools.csharp +code --install-extension ms-dotnettools.csdevkit +code --install-extension ms-dotnettools.vscodeintellicode-csharp + +echo "Installation complete. Please restart your terminal for changes to take effect." diff --git a/src/content/docs/Splashkit/Applications/npm-installation-guide.md b/src/content/docs/Splashkit/Applications/npm-installation-guide.md new file mode 100644 index 00000000..4b39f160 --- /dev/null +++ b/src/content/docs/Splashkit/Applications/npm-installation-guide.md @@ -0,0 +1,86 @@ +# npm installation guide + +npm is a node package manager. We use it to install and resolve package dependencies (e.g. +`npm install`) or run arbitrary commands specified in `package.json` (e.g. `npm run format`). + +## Windows Guide + +### Install Windows Subsystem Linux (WSL) + +Open PowerShell and follow this guide: + +1. Install WSL. + + ```powershell + wsl --install + ``` + +1. Enable the Windows Subsystem for Linux. + + ```powershell + dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart + ``` + +1. Enable Virtual Machine feature. + + ```powershell + dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart + ``` + +1. Restart your computer (this will take longer than usual as it is installing Linux for the first + time). +1. Download the + [WSL2 Kernel update](https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi). +1. Run the installer. Respond _yes_. +1. Return to PowerShell and set WSL2 as the default. + + ```powershell + wsl --set-default-version 2 + ``` + +1. Follow the official + [guide](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-nvm-nodejs-and-npm) + to install node.js and npm on WSL2. + +## Mac Guide + +### Install Homebrew + +1. Open terminal (The Terminal application is located in the Utilities folder in the Applications + folder) +1. Install Xcode from the + [Apple App Store](http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12) +1. In the terminal type: + + ```shell + ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + ``` + +1. Update to the latest version of Homebrew (type in terminal): + + ```shell + brew update + ``` + +1. Restart your computer (this will take longer than usual) + +### Set up Node.js + +1. Open terminal and type + + ```shell + brew install node + ``` + +1. Wait for files to download, then when done test that it is there by typing: + + ```shell + node -v + ``` + + this should return the version installed + +1. Test npm by typing: + ```shell + npm -v + ``` diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/DXBallGame b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/DXBallGame new file mode 100644 index 00000000..ca503032 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/DXBallGame differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/bundles/bundle.txt b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/bundles/bundle.txt new file mode 100644 index 00000000..437af1c8 --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/bundles/bundle.txt @@ -0,0 +1 @@ +FONT,default,VCR_OSD_MONO.ttf diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/bundles/readme.txt b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/bundles/readme.txt new file mode 100644 index 00000000..da469bad --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/bundles/readme.txt @@ -0,0 +1 @@ +You can place bundle scripts in this folder. diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/fonts/VCR_OSD_MONO.ttf b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/fonts/VCR_OSD_MONO.ttf new file mode 100644 index 00000000..dcca687a Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/fonts/VCR_OSD_MONO.ttf differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/fonts/readme.txt b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/fonts/readme.txt new file mode 100644 index 00000000..18d42aac --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/fonts/readme.txt @@ -0,0 +1 @@ +You can place fonts in this folder. Fonts can be otf or ttf files. diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/1.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/1.png new file mode 100644 index 00000000..799f74f0 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/1.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/10.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/10.png new file mode 100644 index 00000000..71ce917f Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/10.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/2.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/2.png new file mode 100644 index 00000000..a8ea2e22 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/2.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/3.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/3.png new file mode 100644 index 00000000..0cfa7c81 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/3.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/4.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/4.png new file mode 100644 index 00000000..0fc84a39 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/4.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/5.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/5.png new file mode 100644 index 00000000..4af38e59 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/5.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/6.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/6.png new file mode 100644 index 00000000..5402d197 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/6.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/7.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/7.png new file mode 100644 index 00000000..b96b602b Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/7.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/8.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/8.png new file mode 100644 index 00000000..5fb536dc Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/8.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/9.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/9.png new file mode 100644 index 00000000..dc955614 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/9.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/ball.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/ball.png new file mode 100644 index 00000000..5c5e6259 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/ball.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiball.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiball.png new file mode 100644 index 00000000..8e3deb02 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiball.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier.png new file mode 100644 index 00000000..fa2b2219 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_3.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_3.png new file mode 100644 index 00000000..830a7c90 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_3.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_4.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_4.png new file mode 100644 index 00000000..c5ddc27c Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_4.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_5.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_5.png new file mode 100644 index 00000000..ef863f21 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/dropped_multiplier_5.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_2.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_2.png new file mode 100644 index 00000000..f406f093 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_2.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_3.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_3.png new file mode 100644 index 00000000..f2a5ff86 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_3.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_4.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_4.png new file mode 100644 index 00000000..2b6f5ee7 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_4.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_5.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_5.png new file mode 100644 index 00000000..570e8776 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_empty_5.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_2.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_2.png new file mode 100644 index 00000000..154c5ae0 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_2.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_3.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_3.png new file mode 100644 index 00000000..8ac95d1f Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_3.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_4.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_4.png new file mode 100644 index 00000000..1fc0f507 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_4.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_5.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_5.png new file mode 100644 index 00000000..bb5f0a9f Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/gauge_full_5.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/icon.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/icon.png new file mode 100644 index 00000000..35131963 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/icon.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiball_block.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiball_block.png new file mode 100644 index 00000000..fa3d29c0 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiball_block.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_3_block.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_3_block.png new file mode 100644 index 00000000..4d4bcb42 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_3_block.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_4_block.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_4_block.png new file mode 100644 index 00000000..51657f85 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_4_block.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_5_block.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_5_block.png new file mode 100644 index 00000000..62b3ca34 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_5_block.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_block.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_block.png new file mode 100644 index 00000000..e6669d25 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/multiplier_block.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/platform.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/platform.png new file mode 100644 index 00000000..35f60e66 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/platform.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/readme.txt b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/readme.txt new file mode 100644 index 00000000..5d8bc906 --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/readme.txt @@ -0,0 +1 @@ +Place images in this folder. SplashKit can work with png, jpeg, jpg, or tif files. diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/title.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/title.png new file mode 100644 index 00000000..7997764f Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/title.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/transparent.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/transparent.png new file mode 100644 index 00000000..f6e6655f Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/images/transparent.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/json/readme.txt b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/json/readme.txt new file mode 100644 index 00000000..22cb409d --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/json/readme.txt @@ -0,0 +1 @@ +You can place json file in this folder for your program to read. diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/json/scores.json b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/json/scores.json new file mode 100644 index 00000000..a4f941a6 --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/json/scores.json @@ -0,0 +1,46 @@ +{ + "default_values": { + "initials": "--", + "score": 0 + }, + "row0": { + "initials": "HF", + "score": 2 + }, + "row1": { + "initials": "--", + "score": 1 + }, + "row2": { + "initials": "--", + "score": 1 + }, + "row3": { + "initials": "--", + "score": 1 + }, + "row4": { + "initials": "--", + "score": 0 + }, + "row5": { + "initials": "--", + "score": 0 + }, + "row6": { + "initials": "--", + "score": 0 + }, + "row7": { + "initials": "--", + "score": 0 + }, + "row8": { + "initials": "--", + "score": 0 + }, + "row9": { + "initials": "--", + "score": 0 + } +} diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/hurt_c_08-102842.wav b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/hurt_c_08-102842.wav new file mode 100644 index 00000000..9a476ef4 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/hurt_c_08-102842.wav differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/message-incoming-132126.wav b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/message-incoming-132126.wav new file mode 100644 index 00000000..83c9a97e Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/message-incoming-132126.wav differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/readme.txt b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/readme.txt new file mode 100644 index 00000000..06ca9c88 --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/readme.txt @@ -0,0 +1 @@ +You can place sound effects in this folder. SplashKit can play ogg, wav, mod, flac, and mp3 diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/stop-13692.wav b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/stop-13692.wav new file mode 100644 index 00000000..0b8d3917 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/stop-13692.wav differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/video-game-powerup-38065.wav b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/video-game-powerup-38065.wav new file mode 100644 index 00000000..5287600d Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/video-game-powerup-38065.wav differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/winsquare-6993.wav b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/winsquare-6993.wav new file mode 100644 index 00000000..08d99487 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/Resources/sounds/winsquare-6993.wav differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/logs/splashkit.log b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/logs/splashkit.log new file mode 100644 index 00000000..b5577455 --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/DXBall/logs/splashkit.log @@ -0,0 +1 @@ +(14/09/2023) WARNING -> Unable to locate bundle file for game_bundle (/workspaces/Asteroids_Sound/.devcontainer/DXBall/Resources/bundles/bundle.txt) [raised in bundles.cpp:77] diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/devcontainer.json b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/devcontainer.json new file mode 100644 index 00000000..fca1ced4 --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/devcontainer.json @@ -0,0 +1,32 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/dotnet +{ + "name": "SplashKit C++, C# (.NET)", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/dotnet:0-7.0", + "postCreateCommand": ".devcontainer/splashkit-install.sh", + // "runArgs":["--tty","--interactive","-e \"PULSE_SERVER=/mnt/wslg/PulseServer\"","-v/mnt/wslg/ :/mnt/wslg/"] + // "runArgs":["-v \\\\wsl$\\Ubuntu\\mnt\\wslg:/mnt/wslg/"] + // "runArgs": ["--mount, source=\\\\wsl$\\Ubuntu\\mnt\\wslg,target=/mnt/wslg/"] + "mounts": [ + "source=\\\\wsl.localhost\\Ubuntu\\mnt\\wslg,target=/mnt/wslg/,type=bind,consistency=cached" + ], + "containerEnv": { + "PULSE_SERVER": "/mnt/wslg/PulseServer" + } + // Features to add to the dev container. More info: https://containers.dev/features. + // "features": {}, + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [5000, 5001], + // "portsAttributes": { + // "5001": { + // "protocol": "https" + // } + // } + // Use 'postCreateCommand' to run commands after the container is created. + // "postCreateCommand": "dotnet restore", + // Configure tool-specific properties. + // "customizations": {}, + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/splashkit-install.sh b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/splashkit-install.sh new file mode 100644 index 00000000..81ba280b --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer/splashkit-install.sh @@ -0,0 +1,74 @@ +#!/bin/bash + +GIT_SKM_REPO=https://github.com/splashkit/skm.git + +HOME_PATH=/home/vscode +INSTALL_PATH="${HOME_PATH}/.splashkit" + + +function report_missing_git () { + if [[ `uname` = Darwin ]]; then + echo "Developer tools not installed, please run: \"xcode-select --install\" in the terminal and then reinstall." + elif [[ `uname` = MINGW* ]] || [[ `uname` = MSYS* ]]; then + echo "Git not found. Please run \"pacman -S git --noconfirm;\" in the terminal and then reinstall" + elif [[ `uname` = Linux ]]; then + echo "Please install git using your package manager For example: sudo apt install git" + fi + exit 1 +} + +command -v git >/dev/null 2>&1 || report_missing_git + +if [ -d "${INSTALL_PATH}" ]; then + echo "Looks like you already have splashkit!" + echo "To uninstall run \"rm -rf ${INSTALL_PATH}\"" + exit 1 +fi + +git clone --depth 1 --branch master $GIT_SKM_REPO "${INSTALL_PATH}" + +# Add SKM app to path without needing sudo + +# Add to .bashrc if using bash +if [[ ${SHELL} = "/bin/bash" ]] || [ ${SHELL} = "/usr/bin/bash" -a `uname` = Linux ] ; then + echo "export PATH=\"$INSTALL_PATH:\$PATH\"" >> ~/.bash_profile + echo "export PATH=\"$INSTALL_PATH:\$PATH\"" >> ~/.bashrc +fi + + +export PATH="$INSTALL_PATH:$PATH" + +find "${INSTALL_PATH}" -name "*.sh" -exec chmod a+x "{}" \; + +sudo apt-get update +sudo apt-get install -y cmake libpng-dev libcurl4-openssl-dev libsdl2-dev libsdl2-mixer-dev libsdl2-gfx-dev libsdl2-image-dev libsdl2-net-dev libsdl2-ttf-dev libmikmod-dev libncurses5-dev libbz2-dev libflac-dev libvorbis-dev libwebp-dev libfreetype6-dev build-essential + +echo "Configuring SplashKit" +cd "${INSTALL_PATH}/source" +pwd +cmake . + +if [ $? -ne 0 ]; then + echo "Configuration failed" + exit $? +fi + +echo "Compiling SplashKit..." +make +if [ $? -ne 0 ]; then + echo "Compilation failed" + exit $? +fi + +echo "Installing compiled SplashKit library..." +make install +if [ $? -ne 0 ]; then + echo "Install failed" + exit $? +fi + +echo "SplashKit Installed" + +echo Installing pulseaudio +sudo apt-get install -y pulseaudio +echo PulseAudio Installed diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/ReadMe.md b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/ReadMe.md new file mode 100644 index 00000000..f6bb335d --- /dev/null +++ b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/ReadMe.md @@ -0,0 +1,124 @@ +--- +title: "Splashkit Windows Development Contatiner" +description: Initial Creation of Splashkit Development containt and instructions for Windows +author: Philip Williams +date: 13/09/2023 +tags: Splashkit, development enviroment, docker, WSL +--- + +# Splashkit Windows Development Contatiner + +## Introduction + +This dev contatiner can be used to quickly spin up a Docker Linux enviroment sutible for C++ and C# +coding with SplashKit. This envvisoment is based on microsfots C# dev enroiment using dontnet 7.0 +https://github.com/devcontainers/templates/tree/main/src/dotnet and uses VS code as an IDE + +If you want to know more about dev contatiner in genral start with +https://code.visualstudio.com/docs/devcontainers/containers they are very powerful and useful and +greate when working on different projects especailly if they requrie different version of the same +framework. + +## Requriments + +This dev enviroment relies on WSL to display graffics and sound. + +## Testing + +This enviroment hs been tested on + +- Windows 11 Pro 22H2 +- Docker Desktop for Windows v4.22.1 +- WSL 2 (5.15.90.1-microsoft-standard-WSL2) +- (WSL) Ubuntu 22.04.2 LTS +- (Dev Enviroment) Debian GNU/Linux 11 (bullseye) + +## Fist Time Setup + +### Install WSL + +If you have WSL installed this can be skipped + +1. Open command promt (or powershell) as Admin and run + ``` + WSL --install + ``` +1. Check WSL is installed with ubuntu and running WSL 2 + ``` + wsl --status + ``` + ![Image of Cmd with wsl --staus output](images/wsl--status.png) + +### Docker Install + +See https://docs.docker.com/desktop/wsl/ for detail around docker and WSL + +1. Download Docker Desktop for windows https://www.docker.com/products/docker-desktop/ +1. Run the downloaded install `Docker Desktop Installer`, Accept UCA controle and click ok to + install. +1. If prompted to Enable WSL during installtion click yes. +1. Once Installed check WSL is enabled + + - Got to settings + - Genral + - Ensure `Use the WSL 2 based engin` is checked + + ![Docker Settings shwoing WSL 2 Bansed engine enabled](images/DockerSettings_WSL2.png) + +### Setup VS Code + +This guide assumes you already have VS Code Installed + +1. Open Vs Code +1. Search the exstension store for Dev Containers by microsoft or Marketplace Link: + https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers +1. Install the plugin + +# Using Splashkit Dev Contatiner + + + +## Setup + +At this stage you will have to manaully add the dev container to your project. + +1. Copy the [.devcontainer](docs/Splashkit/DevEnviroment/Windows_DevContainer/.devcontainer) folder + and past it in your project directory. +1. In VS Code click open remote window in the bottome left hand corner + ![Open Remote Window button in VSCode](images/RemoteWindowVSCode.png) +1. This will open the Remote Windows opetions in the Command Palette, select `Reopen in Container` + + ![VSCode Command Pallet RemoteWindow](images/VSCodeCommandPalletRemoteWindow.png) + +1. This will start building the container not this will take a while (2-5 Mins on a good PC) You can + watch the progress by clicking Starting Dev Container (showlog) + ![Image Starting Dev Container (showlog)](images/VSCodeStartingDevContainer.png) +1. ![Image Remote Window Splashkit C++,C#](image.png) Your Dev Contatiner should now be ready for + use. + +## Testing your Dev Container + +1. Open a terminal in VS Code, this should open a terminal in the remote contatiner. Note user + VSCode and you should be in /workspaces/[Project] + + ``` + Terminal > New Terminal + ``` + +1. Run the `skm` to ensure skm is installed and working, if skm is not found try clsoing and + reopening the terminal. + + ![VSCode Terminal SKM Command](images/VSCodeTerminalSKM.png) + +1. Test Video and Sound to validate the contatiner, a windowed version of DXBall has been included + in the .devcontainer folder +1. Change to the DXBall Folder and run the DXBallGame (note ifyou don't cahgne folders the game can + not find the resources folder) + ``` + cd .devcontainer/DXBall/ + ./DXBallGame + ``` +1. Game Window Will open, Press 1 to start, left and right arrows to move, esc to exit + +![Image DXBall Title screen](images/DXBallTitle.png) +![Image DXBall Title screen Game Play](images/DXBallGamePlay.png) diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DXBallGamePlay.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DXBallGamePlay.png new file mode 100644 index 00000000..c3a6808c Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DXBallGamePlay.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DXBallTitle.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DXBallTitle.png new file mode 100644 index 00000000..7c9e67a3 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DXBallTitle.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DockerSettings_WSL2.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DockerSettings_WSL2.png new file mode 100644 index 00000000..47123bc3 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/DockerSettings_WSL2.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/Remote Window Splashkit C++,C#.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/Remote Window Splashkit C++,C#.png new file mode 100644 index 00000000..1663ba44 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/Remote Window Splashkit C++,C#.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/RemoteWindowVSCode.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/RemoteWindowVSCode.png new file mode 100644 index 00000000..9f417e1a Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/RemoteWindowVSCode.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeCommandPalletRemoteWindow.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeCommandPalletRemoteWindow.png new file mode 100644 index 00000000..02a400e8 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeCommandPalletRemoteWindow.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeStartingDevContainer.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeStartingDevContainer.png new file mode 100644 index 00000000..5464f9e1 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeStartingDevContainer.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeTerminalSKM.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeTerminalSKM.png new file mode 100644 index 00000000..3aeb7ab0 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/VSCodeTerminalSKM.png differ diff --git a/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/wsl--status.png b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/wsl--status.png new file mode 100644 index 00000000..93e23b04 Binary files /dev/null and b/src/content/docs/Splashkit/DevEnviroment/Windows_DevContainer/images/wsl--status.png differ diff --git a/src/content/docs/Splashkit/Extensions/DebianDebPackaging.md b/src/content/docs/Splashkit/Extensions/DebianDebPackaging.md new file mode 100644 index 00000000..2fa9a7d7 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/DebianDebPackaging.md @@ -0,0 +1,71 @@ +**SIT374 Week 4 Splashkit .deb packaging report:** + +**Overview:** + +This report tracks progress and obstacles related to this Trello ticket: +[link](https://trello.com/c/wXo9Dny0/432-create-debian-package-for-splashkit) + +This ticket tracks a change which would decouple Splashkit Manager (SKM) from the splashkit +libraries. The resulting change would be A) documentation of the splashkit .deb packaging process +and B) a .deb file which can be distributed to end users. + +**Testing environment** + +An x86_64 virtual Machine running Debian 12 Stable. The Debian install has non-free software +packages enabled. The testing user account has sudo privileges. + +**Approach** + +1. Compile splashkit library binaries from source files (C++/C#) + +1. Test the .so files against different compilers (G++, Clang++, dotnet, Mono-MCS) with a piece of + [test code](https://splashkit.io/guides/00-00-reading-text/) that requires the Splashkit library + in some form. + +1. Create a .deb package that contains the library binaries, extracts them to a local folder + (/$user/.Splashkit) or similar then updates their .bashrc $PATH to look for these libraries. + Alternatively force a “global” installation through modifying /usr/lib or /usr/local and updating + ld to link these files. + +1. Create a separate VM with the same environment and use dpkg to install the deb file. Try to + compile the same splashkit test code. + +**Testing & Research Outcomes:** + +I have only been able to make rudimentary progress on implementing the first two tasks of this +ticket. + +**Compiling binaries** + +As I have said to the mentoring team Splashkit SDK and SKM are very tightly interlinked and +separating them causes a number of headaches. I have so far been unable to compile the Splashkit +libraries without using SKM to do it because of the inter-dependencies. I have tried different +variations of manually collecting source files and explicitly trying to feed the compiler the +spashkit.cpp file in order to compile the library myself but kept encountering issues. Eventually I +gave up, used SKM to force a “global install” of splashkit and extracted the compiled .so files. + +**Compiling C++ files without SKM** + +Per the documentation I have seen it is my understanding that once SKM has been installed the user +should be able to execute this command to compile a C++ program without having to use SKM. I have +not been able to do this. Executing: “clang++ program.cpp -l SplashKit -o program” Will result in a +compile error saying that splashkit cannot be found. This happens regardless of whether I run skm +new c++ (to generate the include folder) or not. NB I have also tried variations of the “splashkit” +variable changing case, literal filenames, specifying -L flag and pointing to the location of +compiled and uncompiled splashkit libraries, different compilers (g++, clang++) etc. + +**Compiling C++ Directly Linking Compiled Splashkit library** + +Giving the compiler the compiled library directly works and seems to compile splashkit programs as +expected. Have tested with a couple of the example programs (reading input and playing sound) and +both seem to work as expected. Note: this is still dependent on there being a libSplashKit.so file +in /usr/local/lib (which skm global install does) regardless of where the .so file being passed at +compile time lives: + +**Modifying User Properties to link Static Libraries** + +Have tried a couple of different methods of getting the users profile to correctly link to the .so +library file, however I can not get it to associate correctly. Have tried modifying $PATH in +.bashrc, have tried adding LD_LIBRARY_PATH line and pointing to various directories containing the +source and compiled library. Have also tried modifying ld config (opposed to LD_LIBRARY_PATH) and +re-running ldconfig to try to ingest the library. This does not seem to work either. diff --git a/src/content/docs/Splashkit/Extensions/GPIO Support/gpio-support-research.md b/src/content/docs/Splashkit/Extensions/GPIO Support/gpio-support-research.md new file mode 100644 index 00000000..7ad205a9 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/GPIO Support/gpio-support-research.md @@ -0,0 +1,104 @@ +## Spike Outcomes + +--- + +**Title:** Extending SplashKit Library to Support Raspberry Pi 5 and Generic Linux SBCs + +**Author:** Jonathan Tynan + +## Goals / Deliverables + +- This report documenting findings and recommendations. + +## Tasks undertaken + +- Confirming that pigpio does not support Raspberry Pi 5. +- Develop overview of major projects that fit our requirements. +- Explored gpiod/libgpiod for GPIO control on Raspberry Pi 5. +- Investigated lgpio/rgpio for remote GPIO operations and PWM support. +- Evaluating the availability and suitability of C/C++ bindings for each library. + +## What we found out + +Through this spike, we explored various libraries and interfaces for GPIO and PWM control across Raspberry Pi 5 and generic Linux SBCs. Below are our detailed findings: + +### [WiringPi](https://github.com/WiringPi/WiringPi/) + +- Pros: + - Supports both GPIO and PWM operations on Raspberry Pi models, including the Raspberry Pi 5. + - Offers a simple interface well-suited to SplashKit's existing structure, facilitating straightforward integration. + - Community-driven forks are still maintained, providing ongoing updates. +- Cons: + - Lacks support for remote GPIO operations, a crucial feature for SplashKit. + - Since the original project was deprecated, relying on community-maintained forks raises concerns about long-term support and stability. + - May not be a reliable choice for future development due to potential abandonment. + +### [lgpio/rgpio](https://github.com/joan2937/lg) + +- Pros: + - Developed by the same creator as pigpio, offering a familiar interface and functionality. + - Supports remote GPIO operations out-of-the-box, aligning with SplashKit's requirements. + - Provides basic PWM functionality. + - Compatible with the Raspberry Pi 5 and a range of Linux SBCs beyond Raspberry Pi. + - Has C/C++ bindings suitable for our project. +- Cons: + - Being a newer project, it lacks the maturity and extensive community support of pigpio. + - Potential risks in terms of long-term support and unanticipated bugs. + - Limited documentation could extend the integration and development timeline. + +### [gpiod/libgpiod](https://github.com/brgl/libgpiod) + +- Pros: + - The new Linux kernel interface for GPIO control, providing a unified approach across different Linux-based SBCs. + - Offers broad compatibility with modern Linux systems, making it future-proof. + - Supports Raspberry Pi 5 and generic SBCs. + - Provides C bindings compatible with our C/C++ project. +- Cons: + - Integration may be complex due to structural differences from SplashKit’s current setup, requiring significant refactoring. + - Does not natively support PWM; implementing PWM would require a custom solution using the sysfs interface or gpiomem, which are more complex and less performant. + - Lacks remote GPIO support, limiting its utility in replacing pigpio in SplashKit. + +These libraries, in the writers opinion, are currently the most suitable for enable GPIO operations on the Raspberry Pi 5, and potentially on other linux SBC's. +Whether they are ready for integration into SplashKit, is another question entirely. + +## Open issues/risks + +- PWM Functionality: + - Implementing PWM with gpiod/libgpiod requires a custom solution, potentially leading to increased complexity and maintenance overhead. + - The performance of such a custom implementation may not meet SplashKit's requirements. + +- Remote GPIO Operations: + - Maintaining remote GPIO capabilities is crucial for SplashKit. + - WiringPi and gpiod/libgpiod lack this feature, necessitating either a hybrid approach or alternative libraries. + +- Library Maturity and Support: + - Both lgpio/rgpio and gpiod/libgpiod are relatively new, and this may pose risks regarding long-term support. + - Limited documentation might increase the learning curve and integration time. + + +## Recommendations + +- Further Evaluation of lgpio/rgpio: + - Given its support for GPIO control, remote operations, PWM functionality, and C/C++ bindings, lgpio/rgpio is a strong candidate. + - Conduct comprehensive testing to assess performance, stability, and compatibility with SplashKit. + +- Explore Alternatives: + - This is by no means an exhaustive list of options; other libraries may better fulfill SplashKit's requirements. + - Investigate additional libraries that can provide the needed functionalities, possibly with more mature ecosystems. + +- Additional Spikes and Testing: + - Plan further spikes focused on integrating and testing different GPIO libraries. + - Perform performance benchmarking, especially for time-sensitive operations like PWM and remote GPIO control. + +- Long-Term Strategy: + - Monitor updates to pigpio or its forks for potential future support of Raspberry Pi 5 and generic SBCs. + - Stay informed about emerging libraries and technologies that could meet SplashKit's evolving requirements. + + +## Additional Resources + +- [lgpio/rgpio website](https://abyz.me.uk/lg/index.html) +- [gpiod/libgpiod additional information](https://docs.kernel.org/userspace-api/gpio/chardev.html) + - Note: libgpiod is the library provided by the kernel to interact with the linux GPIO character device. +- [Additional Linux Kernel GPIO drivers](https://docs.kernel.org/driver-api/gpio/drivers-on-gpio.html) + diff --git a/src/content/docs/Splashkit/Extensions/Index.md b/src/content/docs/Splashkit/Extensions/Index.md new file mode 100644 index 00000000..dc0ac064 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/Index.md @@ -0,0 +1,14 @@ +# Splashkit Extensions + +Welcome to the Splashkit Extensions section. +Here you'll find documentation on: + +- GPIO Support +- Language Extensions +- MINGW64 Automated Installation +- Python Compatibility +- Debian Packaging +- Missing Swingame Functionalities +- Pacman Package + +Use this section to explore advanced topics, tools, and enhancements available for Splashkit. diff --git a/src/content/docs/Splashkit/Extensions/Language Extensions/Research & Findings/Software Change Request.md b/src/content/docs/Splashkit/Extensions/Language Extensions/Research & Findings/Software Change Request.md new file mode 100644 index 00000000..5718ade0 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/Language Extensions/Research & Findings/Software Change Request.md @@ -0,0 +1,45 @@ +# Software Change Request Form + +**Change Request ID:** Extensions-Python-1 + +## Project Details + +**Project Name:** Language Extensions, Python Compatibility + +**Requested By:** Ben Thomas Software Engineer, Allan Farrell Team Lead + +**Date of Request:** 10-MAY-2022 + +**Change Description:** Removal of HeaderDoc dependency within the SplashKit Translator, to be +replaced with Natural Docs or another alternative. **Change Reason:** User guide documentation for +HeaderDoc was last updated in 2013, and was then +[retired in 2016](https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/HeaderDoc/revision_history/revision_history.html#//apple_ref/doc/uid/TP40001215-CH362-SW1). +HeaderDoc itself does not appear to have been updated since. Additionally, HeaderDoc does not +support Windows. There are available documentation generators that support a wide array of languages +and platforms that are kept up-to-date. + +**Change Impact:** This will expand the scope of the Language Extensions team, requiring work to be +performed on the currently published \*.h HeaderDoc files within the SplashKit core SDK, to make +them compatible with a new documentation generator. Additionally, it will require changes to the +SplashKit Translator's Ruby code, to implement a new documentation generator and remove the +current dependency on HeaderDoc. This change should not impact further development of the SplashKit +core SDK, nor continued investigation and solutions development of the translator itself, as it can +be conducted under a new team. + +**Proposed Actions:** Establishment of a new team under Extensions leadership for future semesters. +Team would create a cloned branch of the current translator, document existing Ruby code functions +and isolate HeaderDoc components. Remove and replace HeaderDoc dependency with alternative +documentation generator. Clone existing SplashKit core SDK and update existing \*.h files to +function with new documentation generator. Test and document functionality. + +**Software Change:** Upon investigation of existing documentation generators, +[Doxygen](https://www.doxygen.nl/) is a strong choice. Existing stable release was updated as recent +as May 2022 and it is cross-platform, including Windows. However, Doxygen does not support Ruby and +there may be plans to utilize documentation generator within the translator, coded in Ruby, in the +future. Best alternative is [Natural Docs](https://www.naturaldocs.org/). Supports 21 languages, +including C++ and Ruby. It is free and open source. Latest version release was Feb 2022 and it +supports multiple platforms, including Windows, macOS, and Linux. + +**Change Priority:** Extensions team consider the priority to be LOW-MODERATE. + +**Change Req. Status:** Proposed. diff --git a/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Detecting Operating System through MSYS.md b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Detecting Operating System through MSYS.md new file mode 100644 index 00000000..2a7f129a --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Detecting Operating System through MSYS.md @@ -0,0 +1,55 @@ +# Detecting Operating System through MSYS2 + +MSYS, or Minimal SYStem, is a Windows software distribution and development platform that offers +package management, a bash shell, and a number of other tools and libraries in a manner reminiscent +of Unix. It is often used in conjunction with MinGW (Minimalist GNU for Windows) to create native +Windows applications using the GNU toolchain. + +## Using Environment Variables + +One common method for detecting the operating system is to leverage pre-defined environment +variables that contain information about the system. MSYS2 provides a variable called `$OSTYPE`, +which holds a string that identifies the operating system type. By checking the value of this +variable, scripts can determine whether they are running on Windows, Linux, macOS, or another +supported platform. + +## Utilizing System Commands + +Another approach involves using system commands that provide information about the current operating +system. The `uname` command, for example, can print various details about the system, including the +operating system name. By parsing the output of this command, scripts can identify the specific +operating system and take appropriate actions. + +## Advantages and Limitations + +Detecting the operating system through MSYS2 offers several advantages: + +1. **Consistent Development Experience:** By using MSYS2, developers can work in a familiar + Unix-like environment, even on Windows, ensuring a consistent development experience across + platforms. + +2. **Portability:** Scripts that detect the operating system through MSYS2 can be easily ported to + other Unix-like environments, as they rely on standard bash features and commands. + +3. **Integration with MinGW:** MSYS2 is often used in conjunction with MinGW, allowing developers to + create native Windows applications using the GNU toolchain. + +However, there are also some limitations to consider: + +1. **Limited to MSYS2 Environment:** The techniques for detecting the operating system are specific + to the MSYS2 environment and may not work in other Windows environments, such as PowerShell or + the native Command Prompt. + +2. **Potential Compatibility Issues:** While MSYS2 aims to provide a Unix-like environment, there + may be compatibility issues with certain Windows-specific tools or libraries. + +3. **Learning Curve:** Developers who are unfamiliar with Unix-like environments or MSYS2 may face a + steeper learning curve when using these techniques. + +## Conclusion + +Detecting the operating system through MSYS2 is a valuable skill for developers working in a +Unix-like environment on Windows. By leveraging environment variables, system commands, and other +techniques, scripts can identify the underlying operating system and adapt their behaviour +accordingly. While there are some limitations to consider, the ability to work in a consistent +development environment across platforms makes MSYS2 a powerful tool for cross-platform development. diff --git a/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Installing Visual Studio Code (VSCode) through MSYS2.md b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Installing Visual Studio Code (VSCode) through MSYS2.md new file mode 100644 index 00000000..d3d06981 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Installing Visual Studio Code (VSCode) through MSYS2.md @@ -0,0 +1,132 @@ +# Installing Visual Studio Code (VSCode) through MSYS2 + +Visual Studio Code (VSCode) is a popular and powerful code editor developed by Microsoft. While it +is primarily designed for Windows, Linux, and macOS, it can also be installed and used on Windows +through MSYS2, a collection of tools and libraries that provide a Unix-like environment for Windows. + +## Understanding MSYS2 + +MSYS2 is a software distribution and building platform for Windows, providing a Unix-like +environment with a bash shell, a package manager (pacman), and a collection of tools and libraries. +It is particularly useful for developers who prefer working in a Unix-like environment or need to +build and run Unix-based applications on Windows. + +MSYS2 includes MinGW, a minimalist development environment that allows you to use the GNU Compiler +Collection (GCC) and other GNU tools to create native Windows applications. This makes it an ideal +choice for installing and using VSCode, which is built on top of Electron, a framework that uses +Node.js and Chromium. + +## Prerequisites + +Before proceeding with the installation, ensure that you have the following prerequisites: + +1. **MSYS2:** Install MSYS2 on your Windows system. You can download the installer from the + [official MSYS2 website](https://www.msys2.org/). + +2. **Updated Package Databases:** After installing MSYS2, open the MSYS2 MinGW 64-bit terminal and + run the following command to update the package databases: + + ``` + pacman -Syu + ``` + + This command will update the core package databases and install any necessary updates. + +## Installing VSCode through MSYS2 + +Follow these steps to install VSCode through MSYS2: + +1. **Install Dependencies:** In the MSYS2 MinGW 64-bit terminal, install the required dependencies + by running the following command: + + ``` + pacman -S --needed base-devel mingw-w64-x86_64-toolchain + ``` + + This command will install the base development tools and the MinGW toolchain, which are necessary + for building and running VSCode. + +2. **Install Node.js:** VSCode is built on top of Electron, which requires Node.js. Install Node.js + by running the following command: + + ``` + pacman -S mingw-w64-x86_64-nodejs + ``` + +3. **Install Git:** Git is a version control system used by VSCode for various purposes, such as + managing extensions and updates. Install Git by running the following command: + + ``` + pacman -S git + ``` + +4. **Install VSCode:** Finally, install VSCode by running the following command: + + ``` + pacman -S code + ``` + + This command will download and install the latest version of VSCode from the MSYS2 repository. + +5. **Launch VSCode:** After the installation is complete, you can launch VSCode by running the + following command in the MSYS2 MinGW 64-bit terminal: + + ``` + code + ``` + + Alternatively, you can search for "Visual Studio Code" in the Windows Start menu and launch it + from there. + +## Configuring VSCode with MSYS2 + +Once VSCode is installed and launched, you may need to configure it to work seamlessly with MSYS2. +Here are a few steps to consider: + +1. **Set the Integrated Terminal:** VSCode has an integrated terminal that can be configured to use + the MSYS2 bash shell. To do this, go to File > Preferences > Settings (or press Ctrl+,) and + search for "terminal.integrated.shell.windows". Set the value to the path of your MSYS2 bash + shell (e.g., "C:\msys64\usr\bin\bash.exe"). + +2. **Configure Build Tasks:** If you plan to use VSCode for building and compiling projects, you may + need to configure the build tasks to use the MSYS2 environment. This can be done by creating a + `tasks.json` file in the `.vscode` folder of your project and specifying the appropriate commands + and environment variables. + +3. **Install Extensions:** VSCode has a rich ecosystem of extensions that can enhance your + development experience. You can install extensions directly from the VSCode Marketplace or + through the MSYS2 package manager. For example, to install the C/C++ extension, run the following + command in the MSYS2 MinGW 64-bit terminal: + + ``` + pacman -S mingw-w64-x86_64-code-cpp + ``` + +## Advantages and Limitations + +Installing VSCode through MSYS2 offers several advantages: + +- **Unix-like Environment:** Developers who are more comfortable working in a Unix-like environment + can benefit from the familiar tools and utilities provided by MSYS2. +- **Consistent Development Experience:** By using MSYS2, you can ensure a consistent development + experience across different platforms, as MSYS2 provides a Unix-like environment on Windows. +- **Access to MSYS2 Packages:** MSYS2 offers a vast collection of packages that can be easily + installed and integrated with VSCode, enhancing its functionality and capabilities. + +However, there are also some limitations to consider: + +- **Performance:** Running VSCode through MSYS2 may introduce some performance overhead, as it adds + an additional layer of abstraction. +- **Compatibility Issues:** While MSYS2 aims to provide a Unix-like environment, there may be + compatibility issues with certain Windows-specific tools or libraries. +- **Learning Curve:** Developers who are unfamiliar with Unix-like environments or MSYS2 may face a + steeper learning curve when using VSCode through MSYS2. + +## Conclusion + +Installing Visual Studio Code (VSCode) through MSYS2 on Windows provides developers with a powerful +code editor in a familiar Unix-like environment. By following the steps outlined in this report, you +can successfully install and configure VSCode to work seamlessly with MSYS2, taking advantage of its +rich ecosystem of tools, libraries, and extensions. While there are some limitations to consider, +the benefits of a consistent development experience and access to MSYS2 packages make this approach +a viable option for developers who prefer working in a Unix-like environment on Windows. diff --git a/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Installing dotnet Report through API.md b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Installing dotnet Report through API.md new file mode 100644 index 00000000..b334ba49 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Installing dotnet Report through API.md @@ -0,0 +1,89 @@ +# Installing dotnet Report through API + +dotnet Report is a powerful reporting and analytics platform that allows developers to seamlessly +integrate reporting capabilities into their applications. While the platform offers various +installation methods, such as Docker, GitHub, and NuGet packages, it also provides an option to +install and integrate dotnet Report directly through an API. + +## Understanding the API Installation Process + +The API installation process for dotnet Report involves leveraging the platform's RESTful API +endpoints to programmatically install and configure the reporting solution within an existing +application. This approach is particularly useful for developers who prefer a more automated and +streamlined integration process or for scenarios where manual installation is not feasible or +desired. + +### Prerequisites + +Before proceeding with the API installation, ensure that you have the following prerequisites in +place: + +1. **API Credentials:** Obtain the necessary API credentials, including the account API token, data + connect API token, and private API token, from the dotnet Report online portal. These credentials + are required to authenticate and authorise the API requests. + +2. **Development Environment:** Set up a development environment with the appropriate tools and + frameworks to interact with the dotnet Report API. This may include an Integrated Development + Environment (IDE), programming language, and any necessary libraries or packages for making HTTP + requests. + +3. **Application Context:** Have a clear understanding of the application context in which you want + to integrate dotnet Report. This includes the target platform, framework, and any specific + requirements or constraints. + +### Installation Steps + +The API installation process typically involves the following steps: + +1. **Authentication:** Authenticate with the dotnet Report API using the provided API credentials. + This step is crucial to ensure that you have the necessary permissions to access and interact + with the API endpoints. + +2. **Configuration:** Configure the dotnet Report installation by sending API requests to set up the + desired reporting environment. This may include specifying the deployment mode (e.g., standalone + or embedded), configuring data sources, and defining report templates or dashboards. + +3. **Integration:** Integrate the dotnet Report components into your application by making API calls + to retrieve and render reports, dashboards, or other reporting artifacts. This step may involve + embedding the reporting functionality into your application's user interface or exposing it as a + separate service. + +4. **Customization:** Customize the reporting experience by leveraging the dotnet Report API to + apply branding, implement access controls, or extend the functionality with additional features + or integrations. + +### Advantages and Limitations + +Installing dotnet Report through the API offers several advantages: + +- **Automation:** A more efficient and repeatable installation procedure can be achieved by + automating the API installation process and integrating it into current deployment pipelines or + continuous integration/continuous deployment (CI/CD) workflows. + +- **Programmatic Control:** Developers have programmatic control over the installation and + configuration process, allowing for greater flexibility and customization based on specific + application requirements. + +- **Scalability:** The API installation approach can be particularly beneficial for scenarios that + require scaling or deploying dotnet Report across multiple environments or instances. + +However, there are also some limitations to consider: + +- **Learning Curve:** Developers need to familiarize themselves with the dotnet Report API and its + documentation, which may introduce a learning curve, especially for those new to the platform. + +- **Complexity:** Depending on the application's requirements and the desired level of + customization, the API installation process may become more complex, requiring additional + development effort. + +- **Maintenance:** As with any API-based integration, ongoing maintenance and updates to the dotnet + Report API may require corresponding updates to the integration code within the application. + +## Conclusion + +Installing dotnet Report through the API provides developers with a programmatic and automated +approach to integrating reporting capabilities into their applications. While this method offers +advantages such as automation, programmatic control, and scalability, it also introduces a learning +curve and potential complexity. Developers should carefully evaluate their specific requirements and +weigh the pros and cons of the API installation approach against other installation methods offered +by dotnet Report. diff --git a/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Understanding MinGW.md b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Understanding MinGW.md new file mode 100644 index 00000000..bab545d6 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/MINGW64 automated installation/Understanding MinGW.md @@ -0,0 +1,90 @@ +# Understanding MinGW + +Using the GNU Compiler Collection (GCC) and other tools from the GNU project, developers can +construct native Windows applications with MinGW (Minimalist GNU for Windows), a lightweight and +open-source development environment. The purpose of this paper is to give readers a thorough grasp +of MinGW's operation and components. + +## Introduction + +MinGW is a collection of free software tools that provide a minimalist development environment for +creating applications on Windows without the need for a full-fledged integrated development +environment (IDE) like Visual Studio. It offers a command-line interface and a set of Unix-like +utilities, allowing developers to work in a familiar environment while targeting the Windows +platform. + +## Components + +MinGW consists of several key components that work together to facilitate the development process: + +1. **GCC Compiler:** A collection of compilers for several programming languages, such as C, C++, + Fortran, and others, is called the GNU Compiler Collection (GCC). It is in charge of converting + executable binaries from source code. + +2. **GNU Binutils:** This package includes essential tools for working with object files, such as + linkers, assemblers, and other utilities. These tools are crucial for combining object files and + libraries into executable programs. + +3. **MinGW Runtime:** MinGW provides a minimal set of runtime libraries that are required for + executing programs compiled with MinGW. These libraries provide functionality similar to the + Microsoft Visual C++ Runtime Libraries but are designed to be lightweight and compatible with the + GNU toolchain. + +4. **MSYS:** MSYS (Minimal SYStem) is a Unix-like shell environment that provides a command-line + interface and various Unix utilities for MinGW. It allows developers to use familiar Unix + commands and tools within the Windows environment, facilitating a smoother transition for those + accustomed to Unix-based systems. + +## Workflow + +The typical workflow when using MinGW to develop applications involves the following steps: + +1. **Writing Source Code:** Developers write their program's source code in a text editor or an + integrated development environment (IDE) that supports MinGW. + +2. **Compiling:** The GCC compiler from the MinGW toolchain is used to compile the source code into + object files. The compiler translates the high-level programming language into machine-readable + code. + +3. **Linking:** After compiling, the linker from the GNU Binutils package combines the object files + with the necessary libraries (including the MinGW runtime libraries) to create an executable + binary file. + +4. **Running:** The resulting executable binary can be run directly on Windows without the need for + additional runtime environments or libraries (apart from the MinGW runtime libraries). + +## Advantages and Use Cases + +MinGW offers several advantages over other development environments: + +1. **Lightweight and Portable:** MinGW provides a minimalist and portable development environment, + making it suitable for developers who prefer working with command-line tools or who want to + create applications without the overhead of a full-fledged IDE. + +2. **Cross-Platform Development:** While MinGW targets the Windows platform, the underlying GNU + toolchain is cross-platform, allowing developers to write code that can be compiled and run on + multiple operating systems with minimal modifications. + +3. **Open-Source and Free:** MinGW is an open-source project, which means that it is freely + available and can be modified and distributed according to the terms of its licence. + +4. **Compatibility with Existing Tools:** MinGW integrates well with existing tools and libraries + from the GNU project, providing developers with a wide range of resources and utilities to + leverage in their projects. + +MinGW is widely used in various scenarios, including: + +- Development of small to medium-sized applications +- Porting Unix-based applications to Windows +- Teaching and learning programming in academic environments +- Embedded systems development +- Open-source projects targeting the Windows platform + +## Conclusion + +MinGW is a powerful and versatile development environment that provides a lightweight and efficient +way to create native Windows applications using the GNU toolchain. By understanding its components +and workflow, developers can leverage the benefits of MinGW and take advantage of its cross-platform +capabilities, open-source nature, and compatibility with existing GNU tools and libraries. Whether +for personal projects, academic purposes, or professional development, MinGW offers a robust and +flexible solution for Windows application development. diff --git a/src/content/docs/Splashkit/Extensions/MissingSwingameFunctionalities.md b/src/content/docs/Splashkit/Extensions/MissingSwingameFunctionalities.md new file mode 100644 index 00000000..9b40aa7d --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/MissingSwingameFunctionalities.md @@ -0,0 +1,141 @@ +# Missing Functionalities from Swingame + +Splashkit is a recreation of an old game engine made by Swinburne University called Swingame, this +document aims to collect missing functions from [Swingame](https://github.com/macite/swingame) to +expand on Splashkit's functionality. Swingame's source code is predominently written in `Pascal` so +these functions will need to be translated before implementing them into Splashkit. + +## Approach + +It is suggested that the missing functionalities are in relation to collision logic. By looking into +the `src` files within the +[Swingame repository](https://github.com/macite/swingame/tree/develop/CoreSDK/src) and comparing +them to that of the Splashkit `src` files, missing functionalities are found and documented. + +## To be added to Splashkit + +The following functions and procedures are located within the +[src](https://github.com/macite/swingame/tree/develop/CoreSDK/src) folder of the Swingame Github +repository, but cannot be located within the +[Splashkit src](https://github.com/splashkit/splashkit-core/tree/develop/coresdk/src/coresdk) files. +All function descriptions are taken from their associated Swingame `src` file. + +### sgPhysics.pas + +- `function BitmapPartPointCollision(bmp: Bitmap; x, y: Single; const part: Rectangle; ptX, ptY: Single): Boolean; overload;` + + - Returns True if a point (`ptX`,`ptY`) is located within the `part` (rectangle) of the bitmap + `bmp` when it is drawn at `x`,`y`, using pixel level collisions. For bounding box collisions use + the rectangle collision functions. The `x` and `y` values specify the world location of the + bitmap. The `ptX` and `ptY` needs to be provided in world coordinates. + +- `function BitmapPartPointCollision(bmp: Bitmap; x, y: Single; const part: Rectangle; const pt: Point2D): Boolean; overload;` + + - Returns True if a point (`pt`) is located within the `part` (rectangle) of the bitmap `bmp` when + it is drawn at `x`,`y`, using pixel level collisions. For bounding box collisions use the + rectangle collision functions. The `x` and `y` values specify the world location of the bitmap. + The point `pt` needs to be provided in world coordinates. + +- `function CellCollision(bmp1: Bitmap; cell1: Longint; x1, y1: Single; bmp2: Bitmap; cell2: Longint; x2, y2: Single): Boolean; overload;` + + - Returns true if the cells within the two bitmaps have collided at their specified x, y + locations. + +- `function CellCollision( bmp1: Bitmap; cell1: Longint; const pt1: Point2D; bmp2: Bitmap; cell2: Longint; const pt2: Point2D): Boolean; overload;` + + - Returns true if the cells within the two bitmaps have collided at the given points. + +- `function CellBitmapCollision(bmp1: Bitmap; cell: Longint; x1, y1: Single; bmp2: Bitmap; x2, y2: Single): Boolean; overload;` + + - Returns true if the cell in the specified bitmap has collided with a bitmap. + +- `function CellBitmapCollision(bmp1: Bitmap; cell: Longint; const pt1: Point2D; bmp2: Bitmap; const pt2: Point2D): Boolean; overload;` + + - Returns true if the cell in the specified bitmap has collided with a bitmap. + +- `function CellBitmapCollision(bmp1: Bitmap; cell: Longint; x1, y1: Single; bmp2: Bitmap; x2, y2: Single; const part: Rectangle): Boolean; overload;` + + - Returns true if the cell in the specified bitmap has collided with a part of a bitmap. + +- `function CellBitmapCollision(bmp1: Bitmap; cell: Longint; const pt1: Point2D; bmp2: Bitmap; const pt2:Point2D; const part: Rectangle): Boolean; overload;` + + - Returns true if the cell in the specified bitmap has collided with a part of a bitmap. + +- `function CellRectCollision(bmp: Bitmap; cell: Longint; x, y: Single; const rect: Rectangle): Boolean; overload;` + + - Returns true if the cell of the bitmap has collided with a given rectangle. + +- `function CellRectCollision(bmp: Bitmap; cell: Longint; const pt: Point2D; const rect: Rectangle): Boolean; overload;` + + - Returns true if the cell of the bitmap has collided with a given rectangle. + +- `function CircleRectCollision(const c: Circle; const rect: Rectangle): Boolean;` + + - Returns True if the Circle collided with rectangle `rect`. + +- `function CircleCircleCollision(const c1, c2: Circle): Boolean;` + + - Returns True if the circles have collided. + +- `function CircleTriangleCollision(const c: Circle; const tri: Triangle): Boolean;` + + - Returns True if the Circle has collided with the Triangle `tri`. + +- `function TriangleLineCollision(const tri: Triangle; const ln: LineSegment): Boolean;` + + - Returns true if the triangle and the line have collided. + +- `function CircleLineCollision(s: Sprite; const line: LineSegment): Boolean;` + + - Returns True if the 'Sprite' `s`, represented by a bounding circle, has collided with a `line`. + The diameter for the bounding circle is based on the sprites width or height value -- whichever + is largest. + +- `function RectLineCollision(s: Sprite; const line: LineSegment): Boolean; overload;` + + - Returns True if the bounding rectangle of the 'Sprite' `s` has collided with the `line` + specified. + +- `function RectLineCollision(const rect: Rectangle; const line: LineSegment): Boolean; overload;` + + - Returns True if the rectangle `rect` provided has collided with the `line`. + +- `function SideForCollisionTest(const velocity: Vector): CollisionSide;` + + - Returns the side of that needs to be checked for collisions given the movement velocity. + +- `procedure CollideCircleLine(s: Sprite; const line: LineSegment);` + + - Perform a physical collision with a circle bouncing off a line. + +- `procedure CollideCircleCircle(s: Sprite; const c: Circle);` + + - Perform a physical collision with a sprite circle bouncing off a stationary circle. + +- `procedure CollideCircleRectangle(s: Sprite; const rect: Rectangle); overload;` + + - Perform a physical collision with a sprite as a circle bouncing off a stationary rectangle. + +- `procedure CollideCircleTriangle(s: Sprite; const tri: Triangle); overload;` + + - Perform a physical collision with a sprite as a circle bouncing off a stationary triangle. + +- `procedure CollideCircles(s1, s2: Sprite);` + - Perform a physical collision between two circular sprites. + +### sgGraphics.pas + +Note: Andrew Cain suggests implementing the `ShowSwinGameSplashScreen` procedure with a Splashkit +animation instead. + +- `procedure ShowSwinGameSplashScreen();` + - Shows the SwinGame intro splash screen. It would be great if you could include this at the start + of your game to help us promote the SwinGame API. + +## Further Contributions + +Contributions on more missing functionalities from Swingame or removal of functionalities added to +Splashkit are encouraged. + +Refer to [CONTRIBUTING.md](https://github.com/thoth-tech/documentation/blob/main/CONTRIBUTING.md) +when contributing to maintain standards and quality of documentation. diff --git a/src/content/docs/Splashkit/Extensions/PacmanPackage.md b/src/content/docs/Splashkit/Extensions/PacmanPackage.md new file mode 100644 index 00000000..b33c2fe0 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/PacmanPackage.md @@ -0,0 +1,93 @@ +# Pacman Package (MSYS2 Mingw64) + +## Overview + +The creation of the pacman installation package aims to remove the need for Splashkit Manager (SKM) +during the installation of the toolkit. This document outlines the progression taken to complete the +[trello ticket](https://trello.com/c/lpkVBT0K) for creating a pacman package, along with the related +obstacles. All referenced files can be found in the +[splashkit-core](https://github.com/thoth-tech/splashkit-core/tree/t1-2024/tools/scripts/pacman) +repository. + +## Approach + +1. Research and understand the needed technical abilities to create a `BUILDPKG` that constructs the + pacman package. + +2. Create a `BUILDPKG` file that incorporates the functionality of the current SKM installation + ([skm-install](https://github.com/thoth-tech/skm/blob/develop/install-scripts/skm-install.sh) & + [global-install](https://github.com/thoth-tech/skm/blob/develop/global/install/skm_global_install.sh)). + Build the package with the said functionalities. + +3. Test the package by compiling [guide code](https://splashkit.io/guides/00-00-reading-text/) that + requires the splashkit library using G++ and Clang++ compilers. Then running the compiled + program. + +4. On a separate testing device, install the package and run the above testing method ensuring it + works when distributed to other devices. + +## Creating BUILDPKG + +In reference to the [MSYS](https://www.msys2.org/wiki/Creating-Packages/) & +[Arch Linux](https://wiki.archlinux.org/title/PKGBUILD) guides on creating packages, it was +determined that the `build()` portion of the `BUILDPKG` file will be used to clone the needed files +from the Github repository into the packages `/src` folder during creation. The `package()` function +then runs commands located here when the user installs the package on there device. The Splashkit +package needs to create the directories `/include/splashkit` & `/lib` within the `/msys64` +directory. Files from the `/src` file will be copied into their needed locations as per the SKM +installation. Once the files have been moved, all locations need to be added to the systems +`PATH ENVIRONMENT` variable. + +## Testing Locally + +The following test was done on a device to build and test the package. + +`makepkg-mingw --cleanbuild --syncdeps --force --noconfirm` is ran to build the package from the +`PKGBUILD` file within the same directory. Installation of the package is done by running +`pacman -U *.pkg.tar.zst` in the same directory. + +Using `clang++ .cpp -l splashkit -o ` we are able to compile the guide code by +linking the Splashkit library from the `/mingw64/include` directory. Running the program using +`./.exe` successfully runs the file with full functionality. + +## Distributed Testing + +The following tests were done on a separate device from the one building the package. + +Installation of the package is done by running pacman -U \*.pkg.tar.zst in the same directory of the +distributed package. + +Using clang++ .cpp -l splashkit -o we are able to compile the guide code by +linking the Splashkit library from the /mingw64/include directory. + +Running the program using ./.exe unsuccessfully runs the file. Giving error messages +related to multiple `.dll` files not being found (see [Troubleshooting](#troubleshooting)). + +## Troubleshooting + +The package worked different on the local testing compared to the distributed testing due to the +processes that were done on each. Local testing, on top of installing the package, also built it +from the `BUILDPKG` file. It was discovered that when the user builds the pacman package, all the +steps within the `BUILDPKG` file are run with the current users’ privileges (admin) so all commands +that require those privileges worked (commands relating to setting the systems `PATH ENVIRONMENT` +variable). + +When the distributed testing is done, it does not matter whether the current environment is run as +administrator, because the pacman package opens a new environment to complete all the commands, that +does not contain admin privileges. Due to this we are unable to set the systems `PATH ENVIRONMENT` +variable within the pacman package, thus the `.dll` files are not known to the system when running +the compiled `.exe` file. + +The current solution for this issue is to run +[skm-install](https://github.com/thoth-tech/skm/blob/develop/install-scripts/skm-install.sh) using +`bash curl` alongside the pacman package, as that runs with admin privileges, changing the +`PATH ENVIRONMENT` variable. However, this contradicts the original purpose of the package as it +relies on SKM to function. + +In order to overcome these issues, there are a few methods that could be considered: + +1. Figuring out how to place the needed `.dll` files in a location that is already part of the + systems `PATH ENVIRONMENT` variable. +2. Depend on current MSYS2 packages during the build stage for certain .dll files +3. How to install the repo into `/msys64/home//.splashkit` dir and adding that to the + `PATH ENVIRONMENT` variable. diff --git a/src/content/docs/Splashkit/Extensions/Python Compatibality/Research & Findings/Python Changelog.md b/src/content/docs/Splashkit/Extensions/Python Compatibality/Research & Findings/Python Changelog.md new file mode 100644 index 00000000..25ebe8ab --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/Python Compatibality/Research & Findings/Python Changelog.md @@ -0,0 +1,31 @@ +# Python Syntax Changelog + +**Purpose:** This document collates specific language changes from Python 3.8 up. It is intended to +aid in the investigation of why Python is functional in 3.7 and earlier, but not later versions. + +**This document is not complete.** + +## Python 3.0 + +Python 3.0 was intentionally developed to be backwards compatible. At the establishment of the +Python project team, we were informed that versions prior to 3.8 functioned as intended with the +translator. This leads to the thinking that the Python 3.8 update is specifically responsible for +the failure in compatibility. + +## Python 3.8 + +**Assignment expression** introduces new syntax, used by :=, to assign values to variables as part +of a larger expression. + +**Positional-only parameters** introduces new notation requirements, using /, to indicate that some +function parameters require positional specificity and cannot be used as arguments. The following +code uses the example that parameters _a_ and _b_ are positional-only, with _c_ and _d_ being +positional or keyword, and _e_ and _f_ being keyword-only. + +**Parallel filesystem cache** introduced new setting used to configure the implicit bytecode cache +so that it can use a separate filesystem tree rather than the default subdirectories. + +**Python documentation** provides a list of +[changes in Python behaviour](https://docs.python.org/3.8/whatsnew/3.8.html#porting-to-python-3-8) +that may require code changes. Additionally, changes to the Python API and C API are included, +though it is unknown if any of these things would affect existing translator functionality directly. diff --git a/src/content/docs/Splashkit/Extensions/Python Compatibality/Research & Findings/TestPythonVersion.md b/src/content/docs/Splashkit/Extensions/Python Compatibality/Research & Findings/TestPythonVersion.md new file mode 100644 index 00000000..7c0293c9 --- /dev/null +++ b/src/content/docs/Splashkit/Extensions/Python Compatibality/Research & Findings/TestPythonVersion.md @@ -0,0 +1,52 @@ +# \*\*Spike Outcomes + +================== + +**Title:** Test Python Version + +**Author:** Darren Marchiano Sunandar + +## Technologies, Tools, and Resources used + +- Programming Languages: +- Python +- Programming Libraries: +- Python libraries +- Text Editor: VsCode +- Terminal + +## Tasks undertaken + +- I've tested all the python function from the Splashkit website guides such as: + +1. Using Splashkit +2. Using Animations in Splashkit +3. Get Started with Splashkit Audio +4. Splashkit Camera (Error in Line 49) +5. Graphics +6. Input +7. Networking +8. Utilities + +- What I didn't test since it doesn't contain a python + +1. Interface +2. Json +3. Raspberry GPIO + +## What we found out + +From all the guides that I tested, there is 1 error: + +- From the Splashkit camera guides. In line 49 fill_rectangle() takes 5 positional arguments but 6 + were given. ![alt text](/Images//PythonFillRectangleError.png) + +[Splashkit Camera Guides](https://splashkit.io/guides/camera/0-using-splashkit-camera/) + +## Recommendations + +- Check the Function Argument: Confirm that fill_rectangle() indeed expects five arguments. Usually, + the arguments might be `color`, `x`, `y`, `width`, `height`. +- Review the Argument Passed: Ensure that there are only 5 argument. +- Update code if necessary: Might need to implement the additional feature seperately or modify how + to call fill_rectangle(). diff --git a/src/content/docs/Splashkit/Index.md b/src/content/docs/Splashkit/Index.md new file mode 100644 index 00000000..43d74798 --- /dev/null +++ b/src/content/docs/Splashkit/Index.md @@ -0,0 +1,13 @@ +# Splashkit Documentation + +Welcome to the Splashkit documentation. +Here you’ll find setup guides, applications, modules, and extension documentation for Splashkit-based projects. + +## Sections: +- Applications +- Dev Environment +- Extensions +- Modules +- Operations +- Tutorials +- Website diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Background/Background b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Background new file mode 100644 index 00000000..0759b3f4 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Background @@ -0,0 +1,19 @@ +# Data Analytics Code Repositories + +The code received for Trimester 1, 2022 was not pulled into the Thoth Tech repository at the +completion of Trimester 3, 2021. All future links to Data Analytics code either within the Thoth +Tech repository or in separated forked repositories will be located within this document. + +## Links to code + +Please add your fork to this list, labelled appropriately, if work is incomplete but ongoing at the +end of the semester. + +- [End of 2021 Repository - Contains Broken/Missing Imports](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/coresdk/src/coresdk) +- [T2 2021 Plan for Scope](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/T2%20Development%20Plan) +- [T1 2022 Data Analytics Code Refactor data_analytics.cpp](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/coresdk/data_analytics.cpp) +- [T1 2022 Data Analytics Code Refactor data_analytics.h](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/coresdk/data_analytics.h) +- [T1 2022 Implementation of Test Showcase](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/test/test_data_analytics.cpp) +- [T1 2022 Implementation of Unit Tests](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/test/unit_tests/unit_test_data_analytics.cpp) + +--- diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Background/Code Repositories.md b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Code Repositories.md new file mode 100644 index 00000000..0759b3f4 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Code Repositories.md @@ -0,0 +1,19 @@ +# Data Analytics Code Repositories + +The code received for Trimester 1, 2022 was not pulled into the Thoth Tech repository at the +completion of Trimester 3, 2021. All future links to Data Analytics code either within the Thoth +Tech repository or in separated forked repositories will be located within this document. + +## Links to code + +Please add your fork to this list, labelled appropriately, if work is incomplete but ongoing at the +end of the semester. + +- [End of 2021 Repository - Contains Broken/Missing Imports](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/coresdk/src/coresdk) +- [T2 2021 Plan for Scope](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/T2%20Development%20Plan) +- [T1 2022 Data Analytics Code Refactor data_analytics.cpp](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/coresdk/data_analytics.cpp) +- [T1 2022 Data Analytics Code Refactor data_analytics.h](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/coresdk/data_analytics.h) +- [T1 2022 Implementation of Test Showcase](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/test/test_data_analytics.cpp) +- [T1 2022 Implementation of Unit Tests](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/test/unit_tests/unit_test_data_analytics.cpp) + +--- diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Background/Epic.md b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Epic.md new file mode 100644 index 00000000..3db002a8 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Epic.md @@ -0,0 +1,64 @@ +# Data Analytics Epic + +## Background / Context + +SplashKit is a live product, which can be improved as per valid suggestions and observations. The +addition of Data Analytics is one of the recognised areas for improvement. + +## Business Value + +The addition of Data Analytics into SplashKit enables more focused classes to be designed for data +science students, rather than only using SplashKit for building games. + +## In Scope + +- SplashKit Core SDK (program code for the feature) +- SplashKit.io (articles on usage of the feature) + +## Out of Scope + +- SplashKit Translator +- SKM + +## What needs to happen + +- Review the code from previous trimesters to determine if any of the existing data frames code can + be reused +- Re-create the expected functionality of data frames, including capabilities to perform the loading + of structured data, multiple data types, data modification and cleaning, standardisation, + transformation, feature selection, feature extraction, and descriptive statistics +- Expand the functionality so that the user can visualise data with customizable parameters through + pie-charts, bar graphs, etc. (potentially through the existing SplashKit drawing modules) +- Produce documentation for the usage of the module +- Assess the potential for integration with the machine learning module + +## Assumptions / Dependencies + +- Everything is customizable by the user (for example, the colours in visualisations) +- Previous contribution code is accessible and working + +## UX/UI Considerations + +N/A + +## Analytics Considerations + +None known + +## Regulation & Compliance Considerations + +N/A + +## Operations / Support / Training Considerations + +- Team members must become familiar with SplashKit, C++, Ninja and CMake +- Advise teams 2 weeks in advance of planned release + +## Acceptance criteria + +- Successful addition of being able to load, record, analyse, and visualize the correct data that is + desired by the users +- Functional and passing QA +- Easy to use (user acceptance testing completed) +- Documentation completed for design decisions and work +- Documentation fits current expectations as set by SplashKit.io and stakeholders diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Background/Software_Requirements_Specification.md b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Software_Requirements_Specification.md new file mode 100644 index 00000000..a9cb1d3b --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Background/Software_Requirements_Specification.md @@ -0,0 +1,53 @@ +# Software Requirement Specification (SRS) Document Template + +## 1. Introduction + +The purpose of Data Analytics module is to allowing users to load datasets from various file +formats, then perform data manipulations and visualization for the goal of extracting useful +insights from the dataset. + +### 1.1 Purpose + +The purpose of Data Analytics module is that it is a tool that allows users to import, create data +visualisations, and use pre-written algorithms to perform statistical analysis of the data, and +pre-process data for use in a machine learning model. + +### 1.2 Intended Audience + +The intended audience is Data Analysts, Machine Learning Engineers, and developers. + +### 1.3 Intended Use + +The intended use of this module is to create data visualisations and preprocess the data to be used +in a machine learning model. + +### 1.4 Scope + +- Create dataframes by importing datasets. Adding and removing rows/columns in a dataset. +- Changing data inside a dataset. +- Preprocessing functionality for cleaning and standardising the dataframe for the goal of making it + fit to be used in a machine learning model. +- Create data visualisations like bar graphs, histograms. + +### 1.5 Definitions and Acronyms + +- Dataset: A collection of data in tabular form. Files ending in comma separated values (.csv), tab + separated values (.tbv), Excel (.xlsx), test (.txt) file extension. +- Dataframe: Representation of dataset as an object in the program which allows users to use method + calls to perform actions on the dataset. +- Standardising: the process of converting data to a common format to enable users to process and + analyse it + +## Overall Description + +### 2.1 User Needs + +### 2.2 Assumptions and Dependencies + +## System Features and Requirements + +### 3.1 Functional Requirements + +### 3.2 External Interface Requirements + +### 3.3 Nonfunctional Requirements diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Index.md b/src/content/docs/Splashkit/Modules/Data Analytics/Index.md new file mode 100644 index 00000000..738fa962 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Index.md @@ -0,0 +1,13 @@ +# Data Analytics Module Index + +Here you will find all resources for the Data Analytics module within the SplashKit project. This +documentation is not only for onboarding purposes, but it keeps all team members and leaders up to +date on progress, issues faced and future scope. + +## Links to SplashKit Modules Documentation: + +- [Background](Background/Index.md) +- [Research & Findings](Research%20&%20Findings/Index.md) +- [Testing](Testing/Index.md) + +--- diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Code_Status_2022_Semester_1.md b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Code_Status_2022_Semester_1.md new file mode 100644 index 00000000..07ac0a86 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Code_Status_2022_Semester_1.md @@ -0,0 +1,76 @@ +# Semester 1 2022 Data Analytics Update + +## State Of Code Received + +There were a few roadblocks that halted progress through the data analytics module. Despite bug +fixes being listed as commits from the 2021 code file, it appeared to have never ran. Poor coding +practices were found throughout, including the following: + +- portable_files_dialog.h library not recognised, which could not be resolved + - It was a very unneccessary addition as it only ran in one method and was not used for similar + things in other methods +- splashkit.h was called inside SplashKit, which broke the code and is something you definitely + should not do +- Most imports required for the code were missing +- Data validation code was lengthy and did not work + - A lot of true/false statements were switched, meaning it would never give a proper result + - Swapped between using poorly written Regex and making their own methods to do the same thing, + both did not work properly +- Display function used import that was Windows operating system only + - Means you could not run the Data Analytics module from Mac or Linux + - Also was poorly written and we never got it working +- Dataframe code looked impressive but without display function working, was hard to see if it was + working properly + - Ran out of time to test each individual method +- Poor coding practices within DataFrame object + - Methods to scale window for no reason + - Bad calculations (+1 and -1 in the same line is redundant) + +This meant that instead of starting with Instance Selection and Data Visualisation, all our efforts +had to go into code quality assurance. + +## Changes Made To Code + +The T3 2021 code required a full rewrite. Imports were fixed by removing and adding required ones +Data validation functions have been rewritten to run. They will need to be re-worked into more +robust objects. + +Dataframes code is not currently included in +[T1 2022 repository](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/coresdk/data_analytics.cpp) +as it does not compile or run. You can find the dataframes code in the +[T3 2021 repository](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse), +data_analytics.cpp from line 369 on. + +## Issues To Be Resolved + +- Review on whether string recognition is required. + - If yes, create dynamic objects for each item to be recognised + - Regex also needs to be improved + - Actioning this is not urgent, but course of action is + - If no, remove altogether, along with tests +- Clean up Dataframes code line by line + - Superfluous code present, needs to be simplified + - Issues identified include: + - Reliance on Windows exclusive console functions, display function is littered with them. + STD_OUTPUT_HANDLE, GetConsoleScreenBufferInfo, hConsole, etc are all exclusive to windows, + need to make multi-platform. Would recommend trying to get it running on a Windows device + first just to make sure it does work before removing windows stuff. (It seems to be using + the windows exclusive functions to check the console window width before printing so it can + format the dataframe correctly. This feature is a nice-to-have, but Mac and Linux support + are MUST HAVES) + - Variable arrays, array size must be known at compile time in C++. This only seems to be an + issue for a couple of the insert functions in the dataframe code, so it is recommended to + comment them out for now and try get it working without them. + - Needs more comments and general simplification -- too hard to understand what the code is + doing. + - Code does not compile or run on Mac or Linux. + - Research Pandas Dataframes and review our current setup + - Add basic functions required for simple implementation +- Create new display function + - Needs to work on all systems +- Test Dataframe code + - As we do not think it has ever compiled or run, we need to determine that all functions and + objects work properly. + - If they do not: either refactor or begin to re-write code based on + [Scope documents](../Scope/Index.md). + - Tests will have to be created as none currently exist for the dataframes. diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Data_Analytics_Scope_T1_2022.md b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Data_Analytics_Scope_T1_2022.md new file mode 100644 index 00000000..a2e26323 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Data_Analytics_Scope_T1_2022.md @@ -0,0 +1,52 @@ +# Scope for Data Analytics Module + +The scope for the data analytics module depends on the finalisation of reviews for the code. + +## Previous Scope + +### Completed + +These are things that were listed as completed, some of these things seem like they were never done +but ticked off. + +- Functions to read in structural dataset + - Column by column indicated by the programmer/computer scientist + - Row by row indicated by the programmer/computer scientist +- Data management design for the analysed datasets + - Dataframe +- Data pre-processing capabilities + - Reading data from files + - Data cleaning + +### To Do + +#### 2022 + +- Data pre-processing capabilities + - Instance selection + - Data standardization + - Data transformation + - Feature extraction and selection + - Create MATLAB-like clear data input space, load data, visualisation, statistics, plots, subplots + +#### Ongoing + +- 1 year: across two trimesters for data visualisation plotting framework – data distribution and + central tendencies – functions for plotting 2D plots and axes formatting. +- 1.5 years: Incorporate with SplashKit - API - Input developed functions for handling inputs and + interactions esp. for window applications +- 2 years: Incorporate with Machine Learning module +- 2.5 years: Data visualisation + +## New Scope: + +### If dataframes can be salvaged + +- Begin ensuring the completed work is there. If not, create cards in Trello for things to be + re-done. +- Create Objects for data Validation, or remove and rebuild at correct stage in former scope. + +### If dataframes can not be salvaged + +- Begin the whole module again. +- Estimate new times for completion based on skill level and research. diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Data_Frame_Redesign_2022_Trimester_2.md b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Data_Frame_Redesign_2022_Trimester_2.md new file mode 100644 index 00000000..582c9534 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Data_Frame_Redesign_2022_Trimester_2.md @@ -0,0 +1,93 @@ +# Trimester 2 2022 Data Frame Redesign + +## Prior state of the Data Frames + +A review completed in Trimester 1 2022 found that there were severe issues in the existing Data +Analytics code. This review found that more modifications and research needed to be completed before +it can be included in the Thoth Tech splashkit-core repository. + +The following points were requested to be researched further: + +1. Review whether or not string recognition is required +2. Review and resolve compatibility issues for Mac and Linux users +3. Determine if the existing Data Frame code works and meets user expectations, otherwise redesign + the Data Frame + +## Research and Findings + +### 1. Review whether or not string recognition is required + +The string recognition code was implemented but not utilised by the Data Frame methods. This code +contained issues with: + +- Hard-coding values, such as requiring 3 decimal places +- Not executing correctly when tested +- Requiring terminal input for issues that could be resolved without the terminal +- Not having a forseeable use case for Data Frames or plotting data + +#### Solution + +The string recognition code has been excluded due to it not being needed for the module. This code +remains accessible for future inspiration if necessary +([URL](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/coresdk/src/coresdk)). + +### 2. Review and resolve compatibility issues for Mac and Linux users + +The issues identified by the trimester 1 2022 team were confirmed, including: + +- Using variables and constants exclusive to Windows machines +- Hard-coding display output sizing to the terminal + +#### Solution + +The Windows exclusive coding artefacts have been removed to ensure that all operating systems can +run the method. In the redesign, the columns are separated by a tab only. This can be modified in +the future as needed to ensure that users can set their data frame sizes appropriately. This code +remains accessible for future inspiration if necessary +([URL](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/coresdk/src/coresdk)). + +### 3. Determine if the existing Data Frame code works and meets user expectations, otherwise redesign the Data Frame + +The existing code was found to have a large number of issues that impact the scalability of the Data +Frame, as well as not meeting many QA criteria. These include: + +- Not designed to allow distinct columns to have different data types +- Not designed to scale as more features are implemented +- Not meeting the MATLAB/SplashKit method style (for example: dataframe.getColumn() vs. + getColumn(dataframe)) +- Limited commenting (a lot of the code and variable names are difficult to interpret) +- A lot of duplicated code +- Some functions not performing as expected +- Many methods are incomplete as well as not containing the same number of opening and closing + parentheses + +Due to the above issues, the Data Frame has been redesigned to be able to meet the requirements of +the module. This code remains accessible for future inspiration if necessary +([URL](https://bitbucket-students.deakin.edu.au/users/zbargiamidis/repos/splashkit2021t3/browse/coresdk/src/coresdk)). + +#### Solution + +The Data Frame has been redesigned with the following considerations: + +- Data Frame is a struct, as per the rest of the SplashKit objects +- Data Frame supports resizing when altering rows and columns + - Using vectors instead of arrays + - Data stored as a vector of columns (so columns can be added or removed) + - Columns are also themselves vectors (so rows can be added or removed) +- Data Frame supports various column types by using a 'variant' type + - C++ is a statically typed language. A number of solutions include: + - Using pointers and casting (defining a column as: vector\ object) + - Using an 'any' type and casting (defining a column as: vector\) + - Using a 'variant' type to allow a set of data types to be stored in the vector (defining a + column as: vector\>) + - All three solutions were coded. + - The 'variant' type produced the simplest API to use as well as having the most interpretable + code. + - The 'any' type led to poor memory efficiency +- Using the SplashKit method naming convention: function(struct) instead of struct.function() +- Unit testing has been created and implemented + +## State of the Data Frames after the research + +- [Active branch](https://github.com/thoth-tech/splashkit-core/tree/modules/data_analytics) (as of + 10/8/2022) diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Index.md b/src/content/docs/Splashkit/Modules/Data Analytics/Research & Findings/Index.md new file mode 100644 index 00000000..e69de29b diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Index.md b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Index.md new file mode 100644 index 00000000..e7fcae21 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Index.md @@ -0,0 +1,24 @@ +# Testing Strategy + +At Thoth Tech, we believe in a testing focused approach to development. Within the Splashkit Module, +there are two types of testing we will undertake. The first is +[building a showcase for our work](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/test/test_data_analytics.cpp) +within the SplashKit core repository. Not only does this show other people our code, but allows us +as developers to dynamically test the code utilising inputs. The second style of testing will come +in the form of +[unit tests](https://github.com/lawrence0arabia/splashkit-core/tree/develop/coresdk/src/test/unit_tests/unit_test_data_analytics.cpp). +These tests are designed to test the robustness of the code, ensuring that there are no bugs when +changes are made. + +## SplashKit Modules Testing Guides + +--- + +Testing should be done concurrently with code development. During the analysis stage, all potential +positive and negative assertions should be considered. In the review stage, you should be writing +tests as well as running current tests and reviewing the structure of the code. + +Below are the testing strategies for the SplashKit Modules team: + +- [Showcase/Testing](Showcase_Tests.md) +- [Unit Tests](Unit_Tests.md) diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Showcase_Tests.md b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Showcase_Tests.md new file mode 100644 index 00000000..29559fc6 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Showcase_Tests.md @@ -0,0 +1,37 @@ +# Showcase Tests + +## What are they for? + +Showcase tests allows us to interact with the module, dynamically testing inputs and outputs as we +change them locally. + +## Where are they located? + +The showcase for the Data Analytics Module is located within the tests folder for the splashkit core +repository. + +## How to implement + +By importing the `data_analytics.h` header file, you can begin utilising the code that has been +recently added. This allows you to call methods and objects created within the data analytics module +and interact with them to see if they display and run properly. The coding needs to be re-usable, +therefore we have set it up as a for loop taking the input from the user to access different +methods. + +## What is implemented? + +Currently we have implemented tests for the data validation work that has been re-structured. These +allow us to see that they are working. These will be removed when we overhaul the data validation +(which is not up to standard). + +## What needs to be added? + +If the dataframes can be fixed, a section for loading, displaying and manipulating the dataframes +will need to be added. If we have to start the code again, all current showcase code will need to be +removed and replaced with new implementation. + +## When to add code to the showcase + +As Thoth Tech takes a testing approach to development, all tests should be built simultaneously with +coding. This will ensure that our code is of the highest quality prior to pushing to the main Thoth +Tech repository. diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Test Cases.md b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Test Cases.md new file mode 100644 index 00000000..ab1284e1 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Test Cases.md @@ -0,0 +1,8 @@ +## Test Plan Template + +### **TEST CASES** + +| # | Scenario | Input | Expected Result | Actual Result | Automated? | +| --- | -------- | ----- | --------------- | ------------- | ---------- | +| | | | | | (Y/N) | +| | | | | | | diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Test Strategy.md b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Test Strategy.md new file mode 100644 index 00000000..30b05fff --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Test Strategy.md @@ -0,0 +1,63 @@ +# **Test Strategy (Sample)** + +## **Introduction** + +A high-level summary of the project + +### **Example** + +This strategy outlines what quality provides to the project, what type of testing is done, and how +testing is carried out. The aim is to ensure quality in all phases of the development lifecycle to +deliver a great experience for our users. + +## **References** + +Relevant links and helpful information about the project and its tech stack + +### **Examples** + +- GitHubproject: \ +- Jasmine is used as a unit testing framework + [https://jasmine.github.io/](https://jasmine.github.io/) +- Cypress is used for end-to-end testing [https://www.cypress.io/](https://www.cypress.io/) +- Karma is used for testing automation + [https://karma-runner.github.io/latest/index.html](https://karma-runner.github.io/latest/index.html) +- App is built using Node.js: [http://nodejs.org/](http://nodejs.org/) + +## **QA Deliverables** + +What artifacts QA will provide to the team (eg, Test Strategy, Sample Test Plan, Bug reports) + +### **Examples** + +- Test plans for each feature +- Issues reported for bugs, enhancements, usability suggestions +- Release process document + +## **Test Management** + +What resources are used to carry out testing in terms of tooling, environments, supported platforms +and versions, and test data + +### **Examples** + +- Jenkins is used to build test versions of the application off of master and PRs +- VMs are used to test the applications in Windows +- Test runs are input in Testpad to make it clear what scenarios were tested and if those scenarios + pass or fail +- Supported operating systems are Windows 7 and 10 and Mac +- Test data will include user accounts + +## **Scope of Testing** + +What types of tests exist for this project? + +### **Examples** + +- There are unit tests, 80% coverage, written in Jasmine +- Written during development—by developers +- Automated UI tests for high-level workflows + +_Based on template from_ +[_Programming Foundations: Software Testing/QA_](https://www.linkedin.com/learning/programming-foundations-software-testing-qa/create-a-test-strategy?autoSkip=true&autoplay=true&contextUrn=urn%3Ali%3AlyndaLearningPath%3A57f7e27c3dd559e018dfe994&resume=false&u=2104084) +_with Meaghan Lewis on LinkedIn Learning_ diff --git a/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Unit_Tests.md b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Unit_Tests.md new file mode 100644 index 00000000..96002055 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Data Analytics/Testing/Unit_Tests.md @@ -0,0 +1,34 @@ +# Unit Test Strategy + +## What is Unit Testing + +Unit testing focuses on small parts (or units) of a code file and tests its robustness. When we +implement a method or object, we want to ensure that it handles the way it is expected to, and shows +the correct error when an input is invalid. + +## How do unit tests work? + +Unit tests can be broken down into three components: + +1. Test Case +1. Section +1. Require Statement + +### Test Case + +A test case is a way of testing objects by comparing the expected and obtained outputs from a +specific input. Each file can have multiple test cases, each of which will focus on a specific +object. An example of a test case currently in use for looking at the data validation section is +`Data Validation will correctly validate different data types`. + +### Section + +Each test case can be broken down into sections. These sections represent the functions that can be +called on each object. + +### Require statement + +This is the part where we compare an output to an expected value. This is done using a `REQUIRE` +statement. These statements only need one parameter as a minimum, a logic statement. This logic +statement will run a method, then check to see if the answer provided is equal to the methods +output. There are many versions of the require method, which can be found in the catch.hpp file. diff --git a/src/content/docs/Splashkit/Modules/Index.md b/src/content/docs/Splashkit/Modules/Index.md new file mode 100644 index 00000000..e69de29b diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Background/Epic.md b/src/content/docs/Splashkit/Modules/Machine Learning/Background/Epic.md new file mode 100644 index 00000000..41f58aba --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Background/Epic.md @@ -0,0 +1,71 @@ +# Machine Learning Epic + +## Background / Context + +SplashKit is a live product, which can be improved as per valid suggestions and observations. The +addition of machine learning is one of the recognised areas for improvement. + +## Business Value + +The addition of machine learning enables game developers to develop more interactive and enjoyable +games, where a game player can then co-operate or compete against an AI character. + +## In Scope + +- SplashKit Core SDK (program code for the feature) +- SplashKit.io (articles on usage of the feature) + +## Out of Scope + +- SplashKit Translator +- SplashKit Manager (SKM) + +## What needs to happen + +- Extend the existing code so that the reinforcement learning agent can be applied to a variety of + user games +- Create artificial neural networks in SplashKit so that a wider variety of reinforcement learning + techniques can be implemented +- Produce documentation for the usage of the module +- Assess the potential for integration with the data analytics module + +## Assumptions / Dependencies + +- This module is in the greater `splashkit_lib` namespace +- System has time to train a model and space to save that model for a given game before use. +- System has a clear score to maximise. (Expand on this for less goal oriented AI? e.g. background + NPC) +- There is a discrete time step between moves. +- The search space remains constant for each move. + +## UX/UI Considerations + +- During AI training user needs a general guide of how long the process will take. +- API should follow the conventions of the SplashKit Platform. +- End user should be able to use the system without any training. (i.e. save the model to disk) + +## Analytics Considerations + +N/A + +## Regulation & Compliance Considerations + +N/A + +## Operations / Support / Training Considerations + +- Guides and Documentation should be written for ease of use. +- Team members must become familiar with SplashKit, C++, Ninja and CMake +- Upskilling may be needed if team members do not have prior knowledge of reinforcement learning and + artificial neural networks +- Advise teams 2 weeks in advance of planned release + +## Acceptance criteria + +See [Test Strategy]() + +- Test with multiple games with different properties and genres. +- Test ANN components with regular AI training set. +- Test against human opponent. +- System can produce a move for any given game state in a reasonable amount of time. +- Documentation fits current expectations as set by SplashKit.io and stakeholders diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Background/Software_Requirements_Specification.md b/src/content/docs/Splashkit/Modules/Machine Learning/Background/Software_Requirements_Specification.md new file mode 100644 index 00000000..bf7d4183 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Background/Software_Requirements_Specification.md @@ -0,0 +1,131 @@ +# Software Requirements Specifications (SRS) Document + +### Machine Learning for SplashKit Modules + +## 1. Introduction + +### 1.1 Purpose + +The purpose of the Machine Learning module for SplashKit is to add the ability for users to easily +build a machine co-op or villain character, so that the player can have real challenges that +increase difficulty throughout playing. Specifically, this it to abstract the complexity behind +building an AI for games so that the user can focus on the task at hand rather than the AI used for +demonstrating the game. + +### 1.2 Intended Audience + +The intended audience for this project is the users of SplashKit who want to create games; both +users with no experience who just want to make a game, and users with lots of experience in creating +AI but cannot spend lots of time on the project. + +### 1.3 Intended Use + +The systems intended use is for the creation of AI agents that can be attached to a user's game. A +Game API allows any game to utilise and attach agents to any game. + +### 1.4 Scope + +The scope of the project is to create usable AI agents for games that users implement, without +adding too much overhead for the user. This requires a deployment to a testing system, as well as +deployment to the SplashKit staging platform for Thoth Tech. + +### 1.5 Definitions and Acronyms + +- User: a developer using SplashKit that has made a game with this system. +- end-user: an individual who plays a game created with this system. +- Wrapper: A list of functions that allow the AI to communicate with the game. Among other + functions, it can be used to determine the current game state of a game, check what moves are + available, and make moves. +- Agent: An AI that can find moves for the game based on the game state. +- AI (Artificial Intelligence): A function that can determine the best output for the given input + and possible outputs. +- API (Application Programming Interface): A set of functions that allow the user to interact with + the system +- ANN (Artificial Neural Network): A type of AI that can learn and adapt it's functionality to + improve the output it produces. + +## 2. Overall Description + +### 2.1 User Needs + +The user requirements of the system are that the system must be usable by game programmers that use +SplashKit. These requirements include: + +- Wrapper for the user's game to be implemented by the user +- Adaptability to many different genres of games +- Choice of AI Difficulty +- Ease of use +- Performant in both time, and AI move choice + +These requirements are mainly focused on the user experience, and how the user interacts with the +system. + +### 2.2 Assumptions and Dependencies + +This system has a few assumptions. These include: + +- Users implement required functions that allow the AI standardised access to the game. +- The game has consistent inputs and outputs. +- If the game is to be played in real-time it is given to the AI in discrete steps. +- User allow for CPU time before a game starts for training purposes if required. + +Each of these assumptions is important for the use and requirements of the system. The system should +be able to deal with multiple move requests in quick succession. + +## 3. System Features and Requirements + +### 3.1 Functional Requirements + +The functional requirements of the system are as follows: + +- The system should be able to accept a given Game wrapper for training or initialisation. +- The system should be able to accept a different Game wrapper for playing. +- The system should return readable moves for any given game state to the user whenever requested. + +### 3.2 External Interface Requirements + +The interface for the system is entirely within the SplashKit platform. The system provides API +functions as its external interface. As such, it has the following requirements: + +- The system's interface should be following the same format and design as other sections of the + SplashKit Platform. +- The system should be accessible from the SplashKit API. +- The system should return results in a readable way. + +#### **Communication Interfaces** + +Documentation is to be provided so that the user can know how to use the system. + +#### **Software Interfaces** + +The Machine Learning Module includes the following components: + +- Game wrapper: An API for the user to implement so that an Agent can make moves +- Agents: An Agent can be chosen by the user that works best with the given Game. +- ANN API: An API allowing the user to create and train a Neural Network. + +### 3.3 System Features + +The system mainly focuses on the backend assistance for the user. As such, the features of the +system are as follows: + +- The system accepts a game format so that game states can be read and moves can be made by the AI. +- The system can accept new game states and analyses the game state to produce a move. +- The system returns a move vector containing the information about the move it wishes to play so + that the game state can be updated. This move vector is to be processed by the user. + +### 3.4 Nonfunctional Requirements + +The non-functional requirements of the system largely revolve around the performance, stability, and +maintainability of the system. These include: + +- The system should adapt and work with different games. +- The system can be used by learning developers without extra training. +- The system should be in line with other SplashKit systems. +- Flexibility, Neural Networks may be needed elsewhere the ability to reuse the existing code for + other purposes should be considered. +- The system should be stable for the user, any new feature added must be tested by the developer + before reaching end-users and related features should not be negatively affected. + - Unit tests should be run on affected features to ensure that any changes made do not affect the + existing components. +- The system should provide a move for any given game state in a reasonable amount of time. diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Feature List.md b/src/content/docs/Splashkit/Modules/Machine Learning/Feature List.md new file mode 100644 index 00000000..7cef2845 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Feature List.md @@ -0,0 +1,73 @@ +# Machine Learning Module, Feature List + +## develop branch + +Branch: https://github.com/thoth-tech/splashkit-core/tree/develop +Changes: https://github.com/thoth-tech/splashkit-core/pull/11 + +### Basic ML Neural Networking library (`machine_learning.cpp`, `machine_learning.h`) + +- can be used to make NN models with variable layers in sequential order +- Each layer can have a unique activation function and node count + - Currently only fully connected (Dense) layers with 1 dimensional IO supported + - Currently only Sigmoid and ReLu activation functions supported +- Extra Loss functions can be easily added later on + - Currently only Mean Squared Error (MSE) implemented +- Testing can be found in `test_machine_learning.cpp`, no unit tests yet + +### Game Learning API (`game_learning.cpp` and `game_learning.h`) + +- A `Game` class has been added, any Game that inherits from this class and implements its functions + can use the Game API +- Currently 3 Agents to choose from + - `RandomAgent` + - Plays random moves + - `MinimaxAgent` + - Uses the minimax algorithm to find the optimal move to make + - Very Slow only usable on small games with few possible moves and few moves per game + - Caches results to be faster + - `QAgent` + - Uses the QLearning algorithm to converge to the optimal move to make + - Requires training using the `agent.train()` method before hand + - Stores a big table mapping every possible game state to every possible action + - Plays simulated games against itself + - When it wins it rewards the moves it made so as to increase the probability of choosing + those moves again + - When it loses it punishes the moves it made so as to decrease the probability of choosing + those moves again +- Uses dynamic systems so as to allow any possible game to implement the API while still providing + the AI with machine readable states +- Tested in `test_machine_learning.cpp` currently only `TicTacToe` and `Pong` games have been tested + on the system. + +## modules/machine_learning branch + +Branch: https://github.com/thoth-tech/splashkit-core/tree/modules/machine_learning +Changes: https://github.com/thoth-tech/splashkit-core/compare/develop...modules/machine_learning + +### Basic ML Neural Networking library (`machine_learning.cpp`, `machine_learning.h`) + +- Mini-batch support + - Uses the average delta of a mini-batch during back-propagation + - Only single-threaded so using this feature does not increase performance +- None Activation Function (skips activation function) +- bias support, updates bias during back-propagation + +### Game Learning API (`game_learning.cpp` and `game_learning.h`) + +- SelfPlayAgent + - reduces repeated code for agents that require self-play training +- new DenseAgent + - uses a dense neural network to make decisions + - known bug: converges to a single output solution from any output + +### Testing/Other + +- `matrix_2d.h` and `matrix_2d.cpp` have been modified + - overload more operators (`>=`, `<=`) + - overload in-place operators (`+=`, `-=`, `*=`, `/=`) + - Faster than using the non-in-place operators (`+`, `-`, `*`, `/`) because there is no + construction overhead +- new testing agent + - `TicTacToeHumanAgent` + - implements base `Agent` class to reduce repeated testing code diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/VS Code Guide.md b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/VS Code Guide.md new file mode 100644 index 00000000..9e185870 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/VS Code Guide.md @@ -0,0 +1,33 @@ +# Guide to debugging SplashKit in Visual Studio Code + +I'm assuming you have [VS Code](https://code.visualstudio.com/) installed and have cloned SplashKit +onto your local computer. Otherwise you can follow the +[instructions](https://github.com/thoth-tech/handbook/blob/main/docs/products/splashkit/splashkit.md) +from the [handbook](https://github.com/thoth-tech/handbook). + +1. Open the SplashKit repo in VS Code, this can be done by right-clicking on the root directory and + then clicking _Open with Code_. + - You should see the all of the folders on the left side in the Explorer. + - The main folders of note are: + - `/coresdk/src/coresdk` (Which contains the core sdk code), + - `/projects/cmake` (Which contains the compiler config), + - `/bin/sktest.exe` (Which is the executable we will be debugging). +2. Copy the 2 included files ([`launch.json`](launch.json) and [`tasks.json`](tasks.json)) to the + `/.vscode` folder, and create the folder if it doesn't already exist. + - The [`tasks.json`](tasks.json) contains tasks for Running cmake and make/ninja. These can be + accessed through the Command Palette (`F1`) by typing 'task', Space, and the command name + (`cmake`, `Compile`, `Full Compile`). + - The [`launch.json`](launch.json) contains the configuration for the debugger. This can be + accessed through wither using the Run/Debug menu (`Ctrl+Shift+D`) or pressing `F5`. +3. OS Dependent issues to take care of: + - **Windows**: If you changed the default install location of MSYS `C:/msys64/` you will need to + manually change all references of `C:/msys64/` to the correct location. + - **MacOS**: Install the + [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) extension + from the VSCode extensions tab. +4. Otherwise you are good to go! + - Run the `cmake` task (`F1`, then type `task cmake`), this needs to be run every time you add or + remove files from the SplashKit repo. + - Now you can run the launch config with `F5` or by opening the Run/Debug menu on the left menu + bar and it should automatically compile and run the `sktest.exe` file. Very rarely this can + fail if you try run it in quick succession, if so you can try running it again. diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/launch.json b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/launch.json new file mode 100644 index 00000000..3073cc42 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/launch.json @@ -0,0 +1,81 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "sktest.exe", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/bin/sktest.exe", + "args": [], + "stopAtEntry": false, + "cwd": "${workspaceFolder}/bin", + "environment": [], + "externalConsole": false, + "windows": { + "MIMode": "gdb", + "miDebuggerPath": "C:\\msys64\\mingw64\\bin\\gdb.exe" + }, + "osx": { + "program": "${workspaceFolder}/bin/sktest", + "MIMode": "lldb", + "type": "lldb" // https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb + }, + "linux": { + "program": "${workspaceFolder}/bin/sktest", + "MIMode": "gdb", + "miDebuggerPath": "/usr/bin/gdb" + }, + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + }, + { + "description": "Set Disassembly Flavor to Intel", + "text": "-gdb-set disassembly-flavor intel", + "ignoreFailures": true + } + ], + "preLaunchTask": "Full Compile" // Swap this with "Compile" to skip the cmake step + }, + { + "name": "skunit_tests.exe", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/bin/skunit_tests.exe", + "args": [], + "stopAtEntry": false, + "cwd": "${workspaceFolder}/bin", + "environment": [], + "externalConsole": false, + "windows": { + "MIMode": "gdb", + "miDebuggerPath": "C:\\msys64\\mingw64\\bin\\gdb.exe" + }, + "osx": { + "MIMode": "lldb", + "program": "${workspaceFolder}/bin/skunit_tests", + "type": "lldb" // https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb + }, + "linux": { + "program": "${workspaceFolder}/bin/skunit_tests", + "MIMode": "gdb", + "miDebuggerPath": "/usr/bin/gdb" + }, + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + }, + { + "description": "Set Disassembly Flavor to Intel", + "text": "-gdb-set disassembly-flavor intel", + "ignoreFailures": true + } + ], + "preLaunchTask": "Full Compile" // Swap this with "Compile" to skip the cmake step + } + ] +} diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/settings.json b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/settings.json new file mode 100644 index 00000000..de4e6e91 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/settings.json @@ -0,0 +1,13 @@ +{ + "terminal.integrated.profiles.windows": { + "MINGW64": { + "path": "C:\\msys64\\msys2_shell.cmd", + "args": ["-defterm", "-here", "-no-start", "-mingw64"] + }, + "wsl": { + "path": "C:\\Windows\\system32\\wsl.exe", + "args": ["-d", "Ubuntu"] + } + }, + "terminal.integrated.defaultProfile.windows": "MINGW64" +} diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/tasks.json b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/tasks.json new file mode 100644 index 00000000..75211dad --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/VS Code/tasks.json @@ -0,0 +1,71 @@ +{ + "windows": { + "options": { + "shell": { + "executable": "C:\\msys64\\msys2_shell.cmd", + "args": ["-defterm", "-mingw64", "-here", "-no-start", "-c"] + // "executable": "C:\\Windows\\system32\\wsl.exe", + // "args": ["-d", "Ubuntu"], + } + } + }, + "tasks": [ + { + "type": "shell", + "label": "cmake", + "windows": { + "command": "'cmake -DCMAKE_BUILD_TYPE=Debug -G \"Ninja\"'", + "args": [], + "options": { + "cwd": "${workspaceFolder}\\projects\\cmake" + } + }, + "command": "cmake", + "args": ["-DCMAKE_BUILD_TYPE=Debug", "-G", "Ninja"], + "options": { + "cwd": "${workspaceFolder}/projects/cmake/" + }, + "problemMatcher": [] + }, + { + "type": "shell", + "label": "Compile", + "command": "'ninja'", + "windows": { + "options": { + "cwd": "${workspaceFolder}\\projects\\cmake" + } + }, + "options": { + "cwd": "${workspaceFolder}/projects/cmake/" + }, + "problemMatcher": [] + }, + { + "type": "shell", + "label": "Delete Cache", + "command": "rm -rf CMakeCache.txt CMakeFiles", + "windows": { + "command": "'rm -rf CMakeCache.txt CMakeFiles'", + "options": { + "cwd": "${workspaceFolder}\\projects\\cmake" + } + }, + "options": { + "cwd": "${workspaceFolder}/projects/cmake/" + }, + "problemMatcher": [] + }, + { + "label": "Full Compile", + "dependsOrder": "sequence", + "dependsOn": ["cmake", "Compile"], + "group": { + "kind": "build", + "isDefault": true + }, + "problemMatcher": [] + } + ], + "version": "2.0.0" +} diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/notes.md b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/notes.md new file mode 100644 index 00000000..2fbff1ff --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Research & Findings/notes.md @@ -0,0 +1,104 @@ +# General Notes: + +## Future Prospects + +NEAT (NeuroEvolution of Augmenting Topologies) – Real Time AI Agent? + +Deep auto encoder for feature compression: random board state plus moves available? Encode into a +compressive neural network and decompress for training. Delete decompression stage after training + +## Questions + +- Do we have to work with C++? + - Yes. The main SDK is written in C++ and that is the focus of the SplashKit Modules team for the + foreseeable future. +- Are we allowed to use libraries? + - Not recommended. Library usage should be kept to a minimum. Any proposed library needs to be + accepted by the lead team as it would not only affect the rights/licence of the project but also + the compile process. (Which could have other unintended consequences) + - Libraries that are used must be monitored and updated accordingly (to fix security flaws or + bugs), and also must be compatible with the SplashKit SDK. + +## Artificial Neural Network Design + +A Tensorflow like library needs to be implemented in C++ for neural networks. + +It needs variable layers so that different difficulties can be implemented. +The game API can be bypassed to directly access this library for other purposes. + +## Evaluation + +![Evaluation of QLearning and Minimax shows QLearning with 94% (9492) games won and Minimax with 90% (90) of games won](https://i.imgur.com/8caHmdY.png) +Here is an example of Evaluation of agent performance we can see that QLearning performs optimally. +Since we know Minimax is optimal we can compare it's performance with QLearning and determine if +QLearning is playing at approximately the same level as Minimax. + +# T2 notes: + +The current implementation probably only works for deterministic games this may be a objective to +investigate and test. + +## perf: Improve Minimax with transposition tables + +Similar to how QTable works store previous board states so that you don't calculate the same board +state twice + +## perf: Normalise game.score() + +Ranked score? +Normalise score so that outliers can't change the results as much. +Use rank? +Use [-1, 1] Normalisation? How would a draw work (when 2+ players tie in score)? + +## Create Difficulty/Complexity levels for ML agent + +Create preset agents. + +Easy/Simple/Fast +Normal/Medium/Average +Hard/Complex/Slow + +Change hidden layers to add extra complexity + +Use virtual board states for Hard difficulty that gets the maximum sum of q-values a certain depth +of moves in rather than just the current board state? + +## feat: Allow RewardTable to be saved to file + +Save RewardTable to a file so it can be used later +This way users will be able to distribute the saved RewardTable as part of the game and also train +Agents across extended periods of time. + +## feat: Add Progress Bar to training + +Add a progress bar to the training process + +Divide iterations by x% + +Each x% of iterations print progress? Every x seconds print progress? + +Currently the training process just leaves the user waiting with no indication of progress. This can +be bad when training is taking a long time (hours). + +## feat: Create a parent Agent class or method that allows the user to browse and select the correct Agent for their use. + +Subclass QTrainer and Minimax into the format + +Standardises Agent functions for later features and designs to be easily added/ created +This will improve expandability of the system. + +## feat: Create a benchmarking system for a game to calculate average stats and automatically determine an Agent for the user. + +This is a quality of life improvement for the user. So they can easily determine which Agent is best +for their game. + +## feat: Add Neural Network capabilities + +Source or create functions to allow for neural networks to be added to SplashKit + +This can greatly improve performance when the game is very complex. + +## refactor: Move functions from header file to cpp file + +To fit the more traditional format classes in the header file should be moved into the cpp file with +only function signatures and doc-strings remaining in the header file. diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Test Cases.md b/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Test Cases.md new file mode 100644 index 00000000..5843ed6c --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Test Cases.md @@ -0,0 +1,41 @@ +# Test Cases for Machine Learning + +## Artificial Neural Network + +### Weights + +#### Test 1: Layer training working + +- Create a layer with 1 output +- Save weights +- Train layer on (1 iteration): + - Static input (all ones) + - Static Expected Output (0) +- Assert current weights != original weights + +#### Test 2: Model training working + +- Create a new model with multiple layers (make sure that there is more than one layer and that each + layer is represented at lest once) +- Save weights +- Train model on (1 iteration): + - Static input (all ones) + - Static Expected Output (0) +- Assert current weights != original weights (for each layer) + +#### Test 3: Model training converges + +- Simple 1 input 1 output model +- Input all ones +- Expected output is 0. +- Train on 20 data points +- Assert model outputs <0.5 (binary 0) greater than 50% of the time (is it converging?) +- Measure model performance + +## Game AI + +#### Test 1: New Agent + +- Create a new ANN Agent +- Train on TicTacToe +- Assert never loses against random Agent (draws are allowed) diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Test Strategy.md b/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Test Strategy.md new file mode 100644 index 00000000..a08ff636 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Test Strategy.md @@ -0,0 +1,57 @@ +# **Test Strategy (Sample)** + +## **Introduction** + +The purpose of the Machine Learning module for SplashKit is to add the ability for users to easily +build a machine co-op or villain character, so that the player can have real challenges that +increase difficulty throughout playing. Specifically, this it to abstract the complexity behind +building an AI for games so that the user can focus on the task at hand rather than the AI used for +demonstrating the game. + +### **Example** + +This strategy outlines what quality provides to the project, what type of testing is done, and how +testing is carried out. The aim is to ensure quality in all phases of the development lifecycle to +deliver a great experience for our users. + +## **References** + +Relevant links and helpful information about the project and its tech stack + +- [SplashKit GitHub](https://github.com/thoth-tech/splashkit-core/tree/modules/machine_learning) + - [test_machine_learning.cpp](https://github.com/thoth-tech/splashkit-core/blob/modules/machine_learning/coresdk/src/test/test_machine_learning.cpp) + - [game_learning.cpp](https://github.com/thoth-tech/splashkit-core/blob/modules/machine_learning/coresdk/src/coresdk/game_learning.cpp) + - [game_learning.h](https://github.com/thoth-tech/splashkit-core/blob/modules/machine_learning/coresdk/src/coresdk/game_learning.h) + - [machine_learning.cpp](https://github.com/thoth-tech/splashkit-core/blob/modules/machine_learning/coresdk/src/coresdk/machine_learning.cpp) + - [machine_learning.h](https://github.com/thoth-tech/splashkit-core/blob/modules/machine_learning/coresdk/src/coresdk/machine_learning.h) +- [Tensorflow Keras](https://www.tensorflow.org/api_docs/python/tf/keras) + - A python library for machine learning, we will create a library similar to this for SplashKit in + C++, simplified and designed to be used by learning developers. + +## **QA Deliverables** + +- See [Test Cases.md]() for a list of unit tests to be used. +- See [Testing.md](Testing/Testing.md) for a list of test strategies to be used. + +## **Test Management** + +What resources are used to carry out testing in terms of tooling, environments, supported platforms +and versions, and test data. + +- VS Code configuration files are [available]() for + debugging purposes. +- [test_machine_learning.cpp](https://github.com/thoth-tech/splashkit-core/blob/modules/machine_learning/coresdk/src/test/test_machine_learning.cpp) + is our main testing file and is used to test newly implemented features. + +## **Scope of Testing** + +What types of tests exist for this project? + +- [Test Cases.md]() contains unit tests to be written for the system. +- Regular less automated tests are also to be created as required + ([Testing.md](Testing/Testing.md)). + - Some of these are already available from last trimester. + +_Based on template from_ +[_Programming Foundations: Software Testing/QA_](https://www.linkedin.com/learning/programming-foundations-software-testing-qa/create-a-test-strategy?autoSkip=true&autoplay=true&contextUrn=urn%3Ali%3AlyndaLearningPath%3A57f7e27c3dd559e018dfe994&resume=false&u=2104084) +_with Meaghan Lewis on LinkedIn Learning_ diff --git a/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Testing.md b/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Testing.md new file mode 100644 index 00000000..c9399234 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Machine Learning/Testing/Testing.md @@ -0,0 +1,62 @@ +# Testing + +When testing the system, first a small scale test is done on the individual components of the newly +implemented features, and the old features that need to be adapted to fit the new functions. + +Due to lack of personnel in T1 informal testing is done on a small scale during implementation. This +involves regularly checking if the program compiles, printing intermediate results, and reverting or +double checking any mistakes. + +## Function testing + +Important features are tested more thoroughly using automated or semi-automated testing as functions +in `test_machine_learning.cpp` +Examples of such testing are: + +- `test_reward_table()`, where we ensure initialisation is correct. +- `test_output_value()`, where we ensure initialisation of `OutputValue` is correct and that updates + to the reward values are executed as planned. + +## Agent Testing + +After testing individual components the overall implementation should also be tested. This is again +done in the `test_machine_learning.cpp` file. + +First the `Game` API is tested with a `TicTacToe` game implemented using the API. This is manually +checked over to test if the system is easy to use and the API is not hard to understand or hard to +implement. + +Ideally more games of different genres should be implemented using the `Game` API. Currently only +`TicTacToe` is implemented. +Example games could include: + +- Pong, as a real-time game it covers a wide range of new features to account for and is still + simple to implement. +- Battleship, as a imperfect information game it may pose a challenge to some `Agent` types. It also + has two different phases that could be hard to account for (Choosing locations for battleships, + and targeting enemy battleships) +- Racing game, a simple 2D racing game where the car must drive around a simple track (such as a + circle) in the fastest time, This type of game may pose difficulties to the API as it may be hard + for the user to chose the `InputFormat`, this is because for these types of game the best format + may use virtual sensors attached to the car giving the AI distances from obstacles. + +We use the example games (only `TicTacToe`) to test the Agents to determine whether the Agents are +performing correctly. + +Manual testing using the `play_games()` function involves 3 steps (Currently only applies to 2 +player games): + +1. First we have the Agent verse a random Agent checking for obvious mistakes and checking the + general logic for random positions. +2. Then we have the Agent verse itself in a round of self-play to check what the Agent thinks is the + best possible game. +3. Then we verse the Agent to test any positions that the Agent may struggle with. + +Automated testing is also used to check against the optimal move set using the +`evaluate_agents_random()` testing function. This is currently only possible for small games or to +test relative performance of the AI. We make the AI verse a random Agent over many games to check +it's win rate against the random Agent. We can then compare this win rate against previous versions +of the Agent or we can compare the results against `MinimaxAgent` since we know that it always +performs optimal moves. This testing also ensures that `MinimaxAgent` is performing as expected, as +if it (`MinimaxAgent`) returns a lower (within a certain threshold) win rate than the Agent being +tested it (`MinimaxAgent`) may be faulty. diff --git a/src/content/docs/Splashkit/Modules/Physics/Background/Epic.md b/src/content/docs/Splashkit/Modules/Physics/Background/Epic.md new file mode 100644 index 00000000..0b859051 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Background/Epic.md @@ -0,0 +1,60 @@ +# Physics Epic + +## Background / Context + +SplashKit is a live product, which can be improved as per valid suggestions and observations. The +addition of realistic physics is one of the recognised areas for improvement. + +## Business Value + +The addition of realistic physics enhances the quality and capabilities of games and animations that +users can build in SplashKit. + +## In Scope + +- SplashKit Core SDK (program code for the feature) +- SplashKit.io (articles on usage of the feature) + +## Out of Scope + +- SplashKit Translator +- SplashKit Manager (SKM) + +## What must happen + +- Complete the code review from T2 2022 on the existing collisions and gravity functions. +- Refactor the code to remove any external dependencies on the Box2D library +- Create one-line methods to allow elastic sprite and object collisions as well as gravity +- Expand the methods to include inertia and the sinking of objects +- Produce documentation for the usage of the module + +## Assumptions / Dependencies + +- Previous contribution code is accessible and working + +## UX/UI Considerations + +N/A + +## Analytics Considerations + +None Known + +## Regulation & Compliance Considerations + +N/A + +## Operations / Support / Training Considerations + +- Team members must become familiar with SplashKit, C++, Ninja and CMake +- Up-skilling may be needed if team members do not have prior knowledge of physics +- Advise teams 2 weeks in advance of planned release +- Current supportive documentation exists explaining creation procedures, etc). + +## Acceptance criteria + +- Successful addition of realistic physics into SplashKit +- Functional and passing QA +- Straightforward to use (user acceptance testing completed) +- Documentation completed for design decisions and work +- Documentation fits current expectations as set by SplashKit.io and stakeholders diff --git a/src/content/docs/Splashkit/Modules/Physics/Background/Index.md b/src/content/docs/Splashkit/Modules/Physics/Background/Index.md new file mode 100644 index 00000000..743d17f9 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Background/Index.md @@ -0,0 +1,10 @@ +# Background Index + +Here you will find all documents related to the aim, purpose and requirements for the Physics +module. This documentation will give insight into what the Physics module aims to achieve and what +will be required for it to be completed. + +## Links to Physics Documentation: + +- [Physics Epic](Epic.md) +- [Software Requirements Specification Document](Software_Requirements_Specification.md) diff --git a/src/content/docs/Splashkit/Modules/Physics/Background/Software_Requirements_Specification.md b/src/content/docs/Splashkit/Modules/Physics/Background/Software_Requirements_Specification.md new file mode 100644 index 00000000..9546116a --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Background/Software_Requirements_Specification.md @@ -0,0 +1,133 @@ +# Software Requirement Specification (SRS) Document Template + +## 1. Introduction + +### 1.1 Purpose + +Developers using SplashKit for 2D games have to create their own methods when wanting to add +realistic physics in their game. A dedicated Physics module would allow developers to integrate real +world physics attributes to sprites and objects in their projects. + +### 1.2 Intended Audience + +The intended audience for this project is users of SplashKit who want to create games. Users can +fall on a spectrum between two levels of experience: + +- Users with no experience who just want to make a game +- Users with lots of experience in creating different physics mechanics in games but do not have the + time to create their own methods for their project. + +### 1.3 Intended Use + +The modules intended use is for the addition of realistic physics actions and reactions to 2D games +created with SplashKit. A variety of methods allows physics attributes to be added to any object or +sprite created in a SplashKit project. + +### 1.4 Scope + +The scope of the project is to update current physics attributes that exist in SplashKit and begin +building a core range of methods. These methods include: + +- Gravity +- Sinking +- Projectile motion +- Collisions +- Momentum +- Push +- Velocity +- Acceleration +- Free Falling +- Density +- Impulse + +### 1.5 Definitions and Acronyms + +#### Definitions + +- Gravity: Acceleration force exerted on an object by another body mass (acceleration of ball + falling to earth) +- Sinking: Process of a body being immersed in a liquid and reaching the bottom of the liquid + container. Happens if the density of the body is greater than the density of the liquid, otherwise + the body remains buoyant. +- Projectile Motion: Path of an object that is launched with an angular trajectory and is only + affected by gravity. Path resembles an arc. +- Collisions: Sudden, forceful coming together in direct contact of two bodies +- Elastic collision: Collision where there is no net loss of kinetic energy in the system. +- Inelastic collision: Collision where part of the kinetic energy in the system is changed to some + other form of energy. +- Kinetic energy: Energy of motion (observable as movement of an object). +- Sprite: An image on screen that can move. +- Momentum: A property of a moving body that determines the length of time required to bring it to + rest under the act of a constant force +- Force: A push or pull on an object with mass that causes it to change velocity. +- Push: A force that changes the direction of an object away from you. +- Pull: A force that changes the direction of an object towards you. +- Speed: The rate of change of position of an object in any direction. Measured as a ratio of + distance covered to the time it took to cover that distance. +- Velocity: The rate of change of position of an object in a specific direction. Measured as the + ratio of the vector distance from origin to the time it took to get to the current location. +- Acceleration: The rate of change of velocity of an object. Measured as a ratio of the final + velocity minus the starting velocity to the time elapsed. +- Free Falling: An object that is falling under the sole influence of gravity. +- Terminal Velocity: When the speed of a moving object is no longer increasing or decreasing. In + other words the objects acceleration is 0. +- Density: How compact or concentrated an object is. Measured as mass per unit volume. If two + objects are the same size but have different densities, the higher density object is heavier. +- Impulse: Overall effect of a force acting over time. Also known as change in momentum. Measured as + the ratio of the change in force to the change in time. + +#### Acronyms/Symbols + +- m: metres. Distance measurement. +- km: kilometres. Distance measurement. Equal to 1000 metres. +- g: grams. Mass measurement. +- kg: kilograms. Mass measurement. Equal to 1000 grams. +- m/s or ms^-1: metres per second. Units for speed and velocity +- m/s^2 or ms^-2: metres per second squared. Units for acceleration + +## Overall Description + +### 2.1 User Needs + +The user requirements for this module are that the module must be usable by game programmers that +use Splashkit. These requirements include: + +- Wrapper for the user's game to be implemented by the user +- Each physics attribute can be implemented using a single method call +- Methods must be compatible with existing sprite, bitmap and physics structures. + - Where appropriate attributes can be added, but should be avoided if basic alternative is + available. +- Default values for gravity and liquid density constants are set to earth and water respectively. +- Use of physics methods on individual shapes, bitmaps and sprites only. +- Length scale is settable by the user + +### 2.2 Assumptions and Dependencies + +This module has a few assumptions. These include: + +- Default gravity is standardised to Earths value (9.8 m/s/s/). +- Separate physics methods should be able to coexist without breaking. +- Surface area to be used instead of volume + +## System Features and Requirements + +### 3.1 Functional Requirements + +- Each physics method to be activated with a single method call +- Functional tests created for each method +- Unit tests created for each method + - Logging created where possible + - + +### 3.2 External Interface Requirements + +N/A + +### 3.3 Nonfunctional Requirements + +- Methods for physics attribute calculations should be as reusable as possible + - Not passing through specific objects (for example sprites) +- Module should be compatible with each operating system +- Methods do not slow performance of program. +- Module and methods are scalable for future complexity increases +- Code is readable and commented thoroughly to make it easier to maintain diff --git a/src/content/docs/Splashkit/Modules/Physics/Index.md b/src/content/docs/Splashkit/Modules/Physics/Index.md new file mode 100644 index 00000000..83762cec --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Index.md @@ -0,0 +1,22 @@ +# Physics Module Index + +Here you will find all resources for the Physics module within the SplashKit project. This +documentation is not only for onboarding purposes, but it keeps all team members and leaders up to +date on progress, issues faced and future scope. + +## What To Find In Each Folder + +The Background folder will contain the aim, purpose and requirements for the module. + +Research and Findings will contain any documents related to research and design on tasks within the +module. + +Testing will contain the testing strategy, and test case planning documents. + +## Links to Physics Documentation: + +- [Background](Background/Index.md) +- [Research & Findings](Research%20&%20Findings/Index.md) +- [Testing](Testing/Index.md) + +--- diff --git a/src/content/docs/Splashkit/Modules/Physics/Research & Findings/Index.md b/src/content/docs/Splashkit/Modules/Physics/Research & Findings/Index.md new file mode 100644 index 00000000..70c6ba3e --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Research & Findings/Index.md @@ -0,0 +1,9 @@ +# Research and Findings Index + +Here you will find all documents related to research for design and implementation tasks for the +Physics module. This documentation will give backgrounds onto decisions made and considerations +taken when designing and implementing methods. + +## Links to Physics Documentation: + +- [Physics Module Review T2 2022](Physics_Module_Review_2022_Trimester_2.md) diff --git a/src/content/docs/Splashkit/Modules/Physics/Research & Findings/Physics_Module_Review_2022_Trimester_2.md b/src/content/docs/Splashkit/Modules/Physics/Research & Findings/Physics_Module_Review_2022_Trimester_2.md new file mode 100644 index 00000000..fb407697 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Research & Findings/Physics_Module_Review_2022_Trimester_2.md @@ -0,0 +1,222 @@ +# Trimester 2 2022 Data Frame Redesign + +## Prior state of the Data Frames + +A prior attempt to review the physics module in Trimester 1 of 2022 found that the existing code did +not function. The review found that much of the code in the module needed refactoring before it can +be included in the Thoth Tech splashkit-core repository. Methods were refactored, but never properly +tested or proven to work. + +The following points were required to be researched further: + +1. Review the need for the Box2D library dependency in SplashKit +2. Review current testing implementation and design future tests going forward +3. Determine if the existing physics method implementation works and meets user expectations, + otherwise redesign the module + +## Research and Findings + +### 1. Review the need for the Box2D library dependancy in SplashKit + +The original inherited physics module (which is now inaccessible) was mostly designed around using +the Box2D physics engine. This is an existing external library created by Erin Catto, who works at +Blizzard. Documentation for this can be found at [this link](https://box2d.org/). + +The extent of the Box2D implementation has been limited to the +[physics.cpp](https://github.com/someguy8/splashkit-core/blob/develop/coresdk/src/coresdk/physics.cpp) +and its header file in a forked repository. It is not utilised in any other files and no other +methods interact with it. + +This code contained issues with: + +- Incorrect importing of an external library causing compile issues +- Lack of relevance to the vision of the Physics module +- No compatibility or scope for comaptibility with existing code + +#### Solution + +All references to Box2D have been removed. As there was no dependencies on this physics engine in +other methods, no refactoring was required with the deletion. + +### 2. Determine if the existing Data Frame code works and meets user expectations, otherwise redesign the Data Frame + +#### Solution + +### 3. Review current testing implementation and design future tests going forward + +A solution was implemented in Trimester 1 2022 but as the code could not be compiled, it was never +confirmed to work. Prior to this solution, there was no implementation of testing for any of the +files in the Physics module. + +Issues with the implemented solution were: + +- Poor implementation of player.h and obstacle.h files in coresdk +- Most test cases designed but never implemented +- test_collisons.cpp does not compile +- Use of "splashkit.h" as an include statement + +#### Solution + +The inclusion of player.h and obstacle.h in coresdk have been removed. These have been replaced with +basic sprite initialisation methods inside the collisions testing file. As these headers were not +utilised anywhere else, they were able to be deleted immediately. + +Current design for test cases has remained the same. + +Unit tests for individual methods in physics.cpp and collisions.cpp must be initialised. These are +called unit_test_physics.cpp and unit_test_collisions.cpp which are required to be populated for +each method. These unit tests are to be modelled off the test_cases.md document. + +The test_collisions.cpp file to be refactored to import two sprites and allow the developer to run +individual tests on different systems. + +The following methods in the existing implementation on the modules/physics branch that must be +actioned are: + +- sprite_gravity + - Simplify + - Have a value in vector2d add to velocity vector2d every frame refresh + - Add a scale factor (default being 3 pixels per second) - can be altered + - Calculate acceleration / scale factor + - default gravity is 9.807f + - don't need mass + - Model it off the Free_Falling method +- sprite_push + - Methods should only pass sprites + - Mass should be previously set + - Run tests to see if this velocity change makes sense +- physical_sprites_collision + + - Can be deleted. Needs to be replaced with elastic and inelastic collision methods + +- KINETIC_ENERGY + + - Remove this instance of the overloaded KINETIC_ENERGY function + - To be implemented in a way that can be used on other objects, not just sprites + +- velocity_after_collied + + - Rename to velocity_from_kinetic_transfer + - Flagged for deletion if not utilised in other methods + +- collision_angle + + - Remove. Should be calculated using each sprites attributes and the vector_angle method. If chain + not required, so method can be deleted + +- KINETIC_ENERGY + + - Fix poor function naming conventions as well (if method required) + - Make universal for all objects, pass mass and velocity vector + +- collision + + - Remove + - Currently no circle-circle collision detection built. Should only be implemented after this is + completed. + - Need other components before looking at creating an elastic and inelastic collision function + for two circles + +- rect_collision + + - As above for the circle-circle collisions + +- Free_Falling + + - Remove + - See sprite_gravity above + +- density + + - Swap volume for area in metres squared + - Volume is a 3d physics trait + - Should not take a sprite, only mass and area + - This will make it more versatile + +- sinking_velocity + + - Needs complete refactor + - Research best way to calculate sinking velocity. The current method is calculating momentum + (F) using mass and speed of sprite, then density. + - Default water buoyancy force should be a declared constant + - Pass mass and speed (if required) as parameters instead of Sprite so the method is reusable + - + +- sinking + + - Calculate densities of object and liquid + - Density has to be area x mass as 2d shapes don't have volume + - Use the density method above + - The current logic for the if statements is fine (can be refined). + - Fix the response blocks where sprite velocity is altered + - Make variable and parameter names more descriptive (not F or F_after_water) + +- sprite_momentum_x + + - Rename as momentum + - Parameters are mass and velocity instead of sprite + - To make the method reusable for other object types + - Return mass x velocity + +- sprite_momentum_y + + - Remove. To be replaced with above momentum method as outlined in sprite_momentum + - Velocity is a 2d vector. X and Y values can be extracted and then set + +- sprite_inelastic_collision + + - Confirm maths is correct + - Utilise momentum equation in v_final + - Keep this method in collisions.cpp + +- sprite_elastic_collision + + - Confirm maths is correct + - Keep this method in collisions.cpp + +- sprite_confine_screen + + - Remove. Not relevant to the physics module. + +- sprite_impulse_x + + - Maths is wrong. The calculation used states that the impulse (force multiplied by time) is equal + to the momentum (mass multiplied by velocity). In reality the impulse is equal to mass + multiplied by the change in momentum. + - This can be calculated, but is not necessary for the module at this time + - A card to be created on Trello to investigate where an impulse method could be used. + - Can be removed + +- sprite_impulse_y + + - See sprite_impulse_x + +- sprite_set_impulse_x + + - See sprite_impulse_x + +- sprite_set_impulse_y + - See sprite_impulse_x + +Ensure all naming conventions for methods, parameters, constants and variables are consistent across +the file. + +## State of the Physics module after the research + +- Code from + [forked branch](https://github.com/someguy8/splashkit-core/blob/develop/coresdk/src/coresdk/collisions.cpp) + has been reviewed + - Player.h, obstacle.h, test_collisions.cpp, physics.cpp and physics.h not brought across + - Methods from line 386-765 in forked repository on collisions.cpp have been moved into + physics.cpp where appropriate. All header references moved as well +- The following methods in the existing implementation on the modules/physics branch that have been + refactored are: + + - TBA + +- The following tests have been implemented: + + - TBA + +- [Active branch](https://github.com/thoth-tech/splashkit-core/tree/modules/physics) (as of + 17/9/2022) diff --git a/src/content/docs/Splashkit/Modules/Physics/Testing/Index.md b/src/content/docs/Splashkit/Modules/Physics/Testing/Index.md new file mode 100644 index 00000000..2fb32c12 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Testing/Index.md @@ -0,0 +1,9 @@ +# Testing Index + +Here you will find all documents related to testing for the Physics module. This documentation will +act as guides for how to initialise and use tests within this module + +## Links to Physics Documentation: + +- [Test Strategy](Test%20Strategy.md) +- [Test Cases](Test%20Cases.md) diff --git a/src/content/docs/Splashkit/Modules/Physics/Testing/Test Cases.md b/src/content/docs/Splashkit/Modules/Physics/Testing/Test Cases.md new file mode 100644 index 00000000..ab1284e1 --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Testing/Test Cases.md @@ -0,0 +1,8 @@ +## Test Plan Template + +### **TEST CASES** + +| # | Scenario | Input | Expected Result | Actual Result | Automated? | +| --- | -------- | ----- | --------------- | ------------- | ---------- | +| | | | | | (Y/N) | +| | | | | | | diff --git a/src/content/docs/Splashkit/Modules/Physics/Testing/Test Strategy.md b/src/content/docs/Splashkit/Modules/Physics/Testing/Test Strategy.md new file mode 100644 index 00000000..30b05fff --- /dev/null +++ b/src/content/docs/Splashkit/Modules/Physics/Testing/Test Strategy.md @@ -0,0 +1,63 @@ +# **Test Strategy (Sample)** + +## **Introduction** + +A high-level summary of the project + +### **Example** + +This strategy outlines what quality provides to the project, what type of testing is done, and how +testing is carried out. The aim is to ensure quality in all phases of the development lifecycle to +deliver a great experience for our users. + +## **References** + +Relevant links and helpful information about the project and its tech stack + +### **Examples** + +- GitHubproject: \ +- Jasmine is used as a unit testing framework + [https://jasmine.github.io/](https://jasmine.github.io/) +- Cypress is used for end-to-end testing [https://www.cypress.io/](https://www.cypress.io/) +- Karma is used for testing automation + [https://karma-runner.github.io/latest/index.html](https://karma-runner.github.io/latest/index.html) +- App is built using Node.js: [http://nodejs.org/](http://nodejs.org/) + +## **QA Deliverables** + +What artifacts QA will provide to the team (eg, Test Strategy, Sample Test Plan, Bug reports) + +### **Examples** + +- Test plans for each feature +- Issues reported for bugs, enhancements, usability suggestions +- Release process document + +## **Test Management** + +What resources are used to carry out testing in terms of tooling, environments, supported platforms +and versions, and test data + +### **Examples** + +- Jenkins is used to build test versions of the application off of master and PRs +- VMs are used to test the applications in Windows +- Test runs are input in Testpad to make it clear what scenarios were tested and if those scenarios + pass or fail +- Supported operating systems are Windows 7 and 10 and Mac +- Test data will include user accounts + +## **Scope of Testing** + +What types of tests exist for this project? + +### **Examples** + +- There are unit tests, 80% coverage, written in Jasmine +- Written during development—by developers +- Automated UI tests for high-level workflows + +_Based on template from_ +[_Programming Foundations: Software Testing/QA_](https://www.linkedin.com/learning/programming-foundations-software-testing-qa/create-a-test-strategy?autoSkip=true&autoplay=true&contextUrn=urn%3Ali%3AlyndaLearningPath%3A57f7e27c3dd559e018dfe994&resume=false&u=2104084) +_with Meaghan Lewis on LinkedIn Learning_ diff --git a/src/content/docs/Splashkit/Operations/Distribution Channels/Index.md b/src/content/docs/Splashkit/Operations/Distribution Channels/Index.md new file mode 100644 index 00000000..92f67974 --- /dev/null +++ b/src/content/docs/Splashkit/Operations/Distribution Channels/Index.md @@ -0,0 +1,81 @@ +# Overview + +SplashKit is a product that been developed to abstract away the complexities of programming +languages for novice programmers. However, the tool-chains and development environments required to +use SplashKit can be difficult and confusing to setup for inexperienced users. Some aspects of these +issues have already been eased through the use of SplashKit’s current install script, but it’s been +observed that the initial installation process for “skm" could be further simplified. The +Distribution Channel Team intends to improve the installation process of SplashKit for new users +across all three major operating systems; Windows, Linux and macOS. The result of these improvements +aims to be a single command or executable installation process that yields a working development +environment for SplashKit on Windows, Linux or macOS ready for the user to start using splashkit as +quickly as possible. Decreasing the friction of the installation process aims to stream-line the +setup process for new users, potentially adding both product value to SplashKit - and confidence to +new users. + +## Goals and Objectives + +The primary goals for the Distrobution Channels Team during the first trimester were: + +- Research the existing installation process, the SplashKit management tool `skm`, and possible + methods of improved installation on all three major operating systems. +- Research and report on current known issues with respect to the installation of SplashKit on all + three major operating systems. +- Investigate issues with Mac M1 chip devices (ARM) +- Write and author installation scripts to resolve the known issues for the installation of `skm` + where possible +- Document the status of the project at the end of the trimester +- Report on future possibilities + +## First Trimester's Deliverables + +The planned deliverables and their current status for the first trimester were + +### Investigate core compilation process on Linux. + +[ TBA ] + +### Investigate simple one-step executable to install + +The team conducted research regarding how we could modify the existing operating system installation +scripts in the `skm` project to be stream-lined and handle dependency installation automatically. +Proof of concepts solutions for the Linux and macOS intallation scripts were authored and merged +into [thot-tech/skm](https://github.com/thoth-tech/skm/). + +[A report is available](research-findings/existing-installation.md) describing our research and +findings. + +### Investigate existing installation for MAC + +The team investigated the existing installation process on Apple devices and discovered that the +`skm` tool works out of the box for newer Apple devices that utilise Apple Silicon processors, using +Apple's +[Rosetta Translation Environment](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment). + +The team identified that the upstream project `splashkit-core` could not be compiled using Apple +Silicon devices. A patch was written and submitted to +[thot-tech/splashkit-core](https://github.com/thoth-tech/splashkit-core/pull/1) which enables +compilation under Apple Silicon devices via Rosetta. + +### Is it possible for this to be simpler? + +The team received additional feedback from stakeholders later in the trimester that further +simplifications should be researched through the use of platform dependent package managers such as +`apt`, `pacman`, `brew`, etc. + +### Investigate existing installation for Windows? + +The team investigated the current installation process for Windows and conducted research on +possible solutions for automating the installation process under Windows. The team research two +candidate approaches under Windows. + +1. Utilising `powershell` as an installation script processor to automatically install `Msys2` and + launch the existing Windows `skm` installation script, or; +2. Composing a package for the `chocolately` package manager for Windows. + +[A report is available](research-findings/existing-installation.md) describing our research and +findings. + +## Current status + +[ TBA ] diff --git a/src/content/docs/Splashkit/Operations/Distribution Channels/research-findings/existing-installation.md b/src/content/docs/Splashkit/Operations/Distribution Channels/research-findings/existing-installation.md new file mode 100644 index 00000000..2820cee8 --- /dev/null +++ b/src/content/docs/Splashkit/Operations/Distribution Channels/research-findings/existing-installation.md @@ -0,0 +1,111 @@ +## Overview of existing installation process + +First time users of SplashKit currently must pre-configure and pre-install dependencies of SplashKit +before they can proceed with the installation process. These dependencies are different on each +major operating system. + +The existing installation behaviour is executed using a +[single monolithic cross-platform bash script](https://github.com/thoth-tech/skm/blob/master/install-scripts/skm-install.sh). +This script detects operating system specific requirements, and configures itself accordingly. + +### Microsoft Windows + +Users must install the [Msys2 development environment](https://www.msys2.org/) by downloading and +executing a GUI installer, before manually install `git` using the built-in package management +system `pacman` before proceeding to execute the SplashKit installation script. + +**Potential issues**: + +1. Msys2 has multiple versions supporting both x86 (32 bit) and x86_64 (64 bit) architectures. The + user must determine the correct version to install, which may not be obvious for a less technical + user. + +1. Automated testing or validation of dependency installation is not present. + +1. There are two steps required before the user can begin installing `skm`. If a user incorrectly + executes either of these first two steps, there's a chance the installation of SplashKit won't + succeed. + +### macOS + +Users must manually install Apple's XCode command line tools using the single command +`xcode-select --install` to ensure that `git` is pre-installed before proceeding to execute the +SplashKit installation script. + +**Potential issues**: + +1. Users are + [prompted with a terms and conditions dialogue](https://apple.stackexchange.com/questions/337744/installing-xcode-command-line-tools) + when installing the XCode command line tools. Some users may feel uncomfortable or not understand + the purpose of it. + +### Linux + +Users must manually install two dependencies (`curl` and `git`) using the package manager supported +by their distribution before proceeding to execute the SplashKit installation script. + +**Potential issues**: + +1. Linux distributions don't all use the same package manager. For example, Debian-based + distributions use `apt`, RedHat-based distribution use `rpm`, and Arch uses `pacman`. This makes + giving users direct dependency installation instructions harder. + +1. There's no automated testing or checking that the dependencies were installed correctly. For + example, if `curl` installed correctly but `git` did not, the execution of the SplashKit + installation script may fail in a way that is not obvious to a new user. + +## The existing cross-platform bash installer + +The existing +[cross-platform installation script](https://github.com/thoth-tech/skm/blob/master/install-scripts/skm-install.sh) +checks that `git` is installed, failing with an error message and suggestion to resolve the issue +when it's not. + +The script checks to see if SplashKit is already installed, failing with an error message and a +suggestion on how the user can uninstall if it is already installed. + +The script checks to see if the user is running either the `bash` or `zsh` shell, before appending +the SplashKit installation directory to the users `.rc` or `.profile`. + +If the installation environment is running Linux, the script recommends the user run a second +post-installation command `skm linux install`. This command manages and installs build and linking +dependencies on Linux, by detecting supported package managers and installing these dependencies +using the appropriate package manger (`pacman`, `apt` or `dnf`). + +**Potential issues**: + +1. The suggestion provided to the user to uninstall SplashKit involves a forced recursive path + removal (`rm -rf ~/.splashkit`). If a user mistypes this, they could potentially erase their + entire home directory (for example, `rm -rf ~/ .splashkit` - observe the accidental space between + `~/` and `.splashkit`) + +1. If a user is executing a shell that is neither `bash` nor `zsh`, the splashkit installation + directory will not be correctly added to users `PATH` environment variable. + +1. Depending on the users `shell`, `skm` may not be available immediately after installation unless + the user manually sources their profile again (i.e. `source ~/.bash_profile`). + +1. Linux users need to run a second post-installation command to complete the SplashKit + installation. If users don't see this suggestion, `skm` may not work. + +1. Users are requested to close and open their terminal. + +**Potential improvements**: + +1. When `git` is not installed, the installer could attempt to automatically install it by detecting + which operating system and package manager is available. This would remove the pre-installation + dependency of `git`, allowing users to launch the SplashKit installer without `git` + pre-installed. + +1. When SplashKit is already installed, the installation script could prompt the user asking if + they'd like to re-install. Re-installation and removal of the old directory could be handled by + the script itself, removing the chance of human-error when uninstalling `splashkit` and resolving + the first potential issue. + +1. A post installation "test" could be implemented to test that SplashKit was successfully + installed, and that `skm` can be access from the current shell environment. This would resolve + potential issue #3. + +1. Given a post installation "test" passes and `skm` is accessible, if the current environment is + Linux, the installer could execute the post-installation command to complete Linux dependency + installation (`skm linux install`). This would resolve potential issue #4. diff --git a/src/content/docs/Splashkit/Operations/Distribution Channels/testing/test-strategy.md b/src/content/docs/Splashkit/Operations/Distribution Channels/testing/test-strategy.md new file mode 100644 index 00000000..204250b0 --- /dev/null +++ b/src/content/docs/Splashkit/Operations/Distribution Channels/testing/test-strategy.md @@ -0,0 +1,108 @@ +# **SKM Distribution Channels Test Strategy** + +## **Introduction** + +The SplashKit Operations team has been undergoing work to improve the installation process of +SplashKit's management tool `skm`. Given the nature of this work (writing installation scripts), +there is no fixed testing strategy that available across all three supported operating systems +(Windows, macOS and Linux). Different tools are available for different operating systems, which is +dictated by both technology availability as well as licensing issues. + +### **macOS** + +[macOS cannot be legally run in a virtualised environment](https://discussions.apple.com/thread/6135949#:~:text=It%20is%20only%20legal%20to,to%20VMware%20Fusion%20and%20Parallels.) +unless the host system is also running on Apple hardware, making installation tests through +virtualisation impractical. + +Whilst [unofficial docker images](https://github.com/sickcodes/Docker-OSX) for macOS exist, they are +not formally supported by Apple, making containerised testing also unviable. + +As the +[installation script](https://github.com/thoth-tech/skm/blob/master/install-scripts/mac/skm-install-mac.sh) +for `skm` on macOS operates largely without changing files outside of the user's home directory, +testing the installation script is possible by first uninstalling `skm` (either using the +`skm uninstall` command or simply removing the `~/.splashkit` directory) and then re-executing the +installation script. + +Static bash script analysis should be performed using [ShellCheck](https://www.shellcheck.net/) or +other available bash script analysis tool. + +**Problems with this approach** + +1. If the tester's system already has `git` installed, the pre-installation dependency checking and + installation code paths will not be executed, + +1. If the tester's system has previously had `skm` installed, the environment variables set by the + installation script may remain dangling in the users shell profile file. + +1. This is a manual process and the responsibility is left with the developer or reviewer to fully + test their code. Reviewers may not have access to macOS hardware to test changes with. + +### **Linux** + +Linux can easily be both virtualised and containerised, meaning an automated (or semi automated) +testing strategy for the Linux installation process could be developed using virtual or container +images. Approaching Linux testing using containerisation technology such as Docker would also make +continuous integration systems a possiblity. + +**Problems with this approach** + +1. The complexity of setting up this test environment is arguably higher than the project itself + +1. Linux has many different distributions consisting of different package managers that are used to + install SplashKit dependencies. Docker images would need to be composed for each + distribution/package manager combination to thoroughly test all code paths. + +Since Linux closely shares it's unix file system structure with macOS, most of the macOS manual +testing methods can also be applied to Linux (for example, manually removing `~/.splashkit` and +re-executing the installation script). + +Static bash script analysis should be performed using [ShellCheck](https://www.shellcheck.net/) or +other available bash script analysis tool. + +**Problems with this approach** + +1. If the tester's system already has dependencies of SplashKit installed, the dependency + installation code paths of the installation script will not be executed. + +1. If the tester's system has previously had `skm` installed, the environment variables set by the + installation script may remain dangling in the users shell profile file.. + +1. This is a manual process and the responsibility is left with the developer or reviewer to fully + test their code. Reviewers may have to set up a Linux environment to test changes. + +### **Windows** + +[ TBA ] + +## **References** + +1. [Legality of running macOS in virtualised environments](https://discussions.apple.com/thread/6135949#:~:text=It%20is%20only%20legal%20to,to%20VMware%20Fusion%20and%20Parallels.) + +1. [Unofficial macOS docker images](https://github.com/sickcodes/Docker-OSX) + +1. [ShellCheck - find bugs in your shell scripts](https://www.shellcheck.net/) + +1. [Docker - containerisation technology](https://www.docker.com/) + +1. [Jenkins - continuous integration technology](https://www.jenkins.io/) + +1. [thot-tech/skm - Splash Kit Manager Repository](https://github.com/thoth-tech/skm) + +## **QA Deliverables** + +- This testing strategy planning document +- Issues reported for bugs, enhancements, usability suggestions and items picked up during code + review +- Issues reported by `ShellCheck` for macOS and Linux installation scripts + +## **Test Management** + +- Git is used as the primary source code management tool for the installation of `skm` +- The installation scripts are manually tested on each operating system by the developer +- The installation scripts for macOS and Linux are processed through `ShellCheck`. + +## **Scope of Testing** + +- macOS and Linux are checked via static analysis with `ShellCheck` +- Testing is largely outcome based (did the installation work?) diff --git a/src/content/docs/Splashkit/Operations/Index.md b/src/content/docs/Splashkit/Operations/Index.md new file mode 100644 index 00000000..e69de29b diff --git a/src/content/docs/Splashkit/Operations/Migrate Arcana to Splashkit/Index.md b/src/content/docs/Splashkit/Operations/Migrate Arcana to Splashkit/Index.md new file mode 100644 index 00000000..e69de29b diff --git a/src/content/docs/Splashkit/Operations/Migrate Arcana to Splashkit/Research & Findings/Index.md b/src/content/docs/Splashkit/Operations/Migrate Arcana to Splashkit/Research & Findings/Index.md new file mode 100644 index 00000000..e69de29b diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Camera-guides/using-splashkit-camera.md b/src/content/docs/Splashkit/Tutorials/Reviews/Camera-guides/using-splashkit-camera.md new file mode 100644 index 00000000..bdc345fa --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Camera-guides/using-splashkit-camera.md @@ -0,0 +1,35 @@ +# SplashKit Camera + +Date Reviewed: 3 SEP 2024 + +Reviewed by: Yuyang Yang + +## Description + +A tutorial review of this tutorial has been completed. You have run the code in this tutorial to +ensure that it works properly and outputs the results. Fixed an issue in Python code where the wrong +number of parameters were passed when fill_rectangle() was called, removed extra parameters, made +sure that C# used a top-level statement style, and made sure that the style was consistent with +other languages, changed some text descriptions to more clearly express the relationship between +game coordinates and screen coordinates, And how to achieve dynamic effects through camera movement. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial has: + - [x] C# using top level statements + - [x] C++ + - [x] Python +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/camera/0-using-splashkit-camera/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/164) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- This content looks very good. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Input-guides/mouse-button-inputs.md b/src/content/docs/Splashkit/Tutorials/Reviews/Input-guides/mouse-button-inputs.md new file mode 100644 index 00000000..a93266e6 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Input-guides/mouse-button-inputs.md @@ -0,0 +1,33 @@ +# Using Mouse Inputs + +Date Reviewed: 28 August 2024 + +Reviewed by: Mounika Angadipeta + +## Description + +A tutorial review of the tutorial has been done. The code in this tutorial has been run to ensure +that it works and outputs the results. The code has all the three languages C++, C#, Python. +Modified part of the text description of the sentence and Fixed the Code error of Mouse Location +Functionality Mouse x in C#.All the rest of the C# code follows top-level statements. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial has: + - [x] C# using top level statements + - [x] C++ + - [x] Python +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/input/1-mouse-button-inputs/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/161) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- No suggestions. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Input-guides/reading-text.md b/src/content/docs/Splashkit/Tutorials/Reviews/Input-guides/reading-text.md new file mode 100644 index 00000000..329484f2 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Input-guides/reading-text.md @@ -0,0 +1,32 @@ +# Title Reading Text + +Date Reviewed: 19/09/2024 + +Reviewed by: Hangyu Li + +## Description + +A tutorial review of the "Reading Text" guide. All the codes are tested with no error. The quality +of the tutorial is good and there is no spelling error. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial has: + - [x] C# using top level statements + - [x] C++ + - [x] Python +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/input/0-reading-text/) + +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/188) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +No suggestions. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/JSON-guides/json_intro.md b/src/content/docs/Splashkit/Tutorials/Reviews/JSON-guides/json_intro.md new file mode 100644 index 00000000..c5d3d15b --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/JSON-guides/json_intro.md @@ -0,0 +1,32 @@ +# Introduction to JSON in SplashKit + +Date Reviewed: 25th August 2024 + +Reviewed by:Yuyang Yang + +## Description + +A tutorial review of the tutorial has been done. Modified part of the text description of the +sentence to make the content more coherent and clear. The code in this tutorial has been run to +ensure that it works and outputs the results. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial has: + - [x] C# using top level statements + - [x] C++ + - [x] Python +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/json/0-json_intro/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/156) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- None. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/getting-started-with-servers.md b/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/getting-started-with-servers.md new file mode 100644 index 00000000..09457cf4 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/getting-started-with-servers.md @@ -0,0 +1,35 @@ +# Getting Started With Servers + +Date Reviewed: 9th August 2024 + +Reviewed by: Brianna Laird + +## Description + +This tutorial covers how to create a basic web server using SplashKit, as well as how to create +`skm resources` for making a website. The tutorial goes over how to create a basic web server that +can display "Hello World" as well as one that will display the `index.html` file created during the +tutorial. + +The program code was tested for each language, issues were identified in the C++ version of code +where in step 3 and in step 4 it used `web_server` instead of `start_web_server` which has been now +fixed. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial uses top level statements in C# and C++. +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/networking/0-getting-started-with-servers/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/145) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- I think this one is currently good as is. +- It could be extended though in more of the "website" aspect but not necessary. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/making-RESTful-API-call.md b/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/making-RESTful-API-call.md new file mode 100644 index 00000000..2dc45334 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/making-RESTful-API-call.md @@ -0,0 +1,36 @@ +# How to make a RESTful API call using SplashKit + +Date Reviewed: 9th August 2024 + +Reviewed by: Brianna Laird + +## Description + +This tutorial covers how to create a JSON object and make a RESTful API call using SplashKit. The +tutorial goes over using GET resources and POST resources. The tutorial also covers how to handle +the response from the API call. + +The guide only contained code for C++, this was reviewed and tested by following the tutorial. A fix +was made in the C++ code where there was an issue with `to_string`. Then a C# code version and +python code version was created and tested to ensure they work correctly and fit into what the C++ +code was trying to accomplish. I also included examples of what the outputs should be. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial uses top level statements in C# and C++. +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/networking/2-restful-api-call/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/147) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- I think this one is good as is. +- If someone did have more experience in understanding RESTful API calls then this could also be + added. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/routing-with-servers.md b/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/routing-with-servers.md new file mode 100644 index 00000000..07ea189d --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Networking-guides/routing-with-servers.md @@ -0,0 +1,36 @@ +# Routing With Servers + +Date Reviewed: 9th August 2024 + +Reviewed by: Brianna Laird + +## Description + +This tutorial extends upon the Getting Started with Servers tutorial by adding in how you can handle +different requests as well as multiple requests at the same time to different html pages within the +project. It also gives a brief explanation on adding links to the html pages to navigate between +them. + +The program code was tested for each language, issues were identified in the C++ version of code in +the recap part where it used `web_server` instead of `start_web_server` which has been now fixed. In +addition the C# code in checking requests was updated to instead use top level statements. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial uses top level statements in C# and C++. +- [x] This tutorial has C#, C++ and Python. +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/networking/1-routing-with-servers/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/146) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- I think there is potential to extend the adding links area and building different html pages. + Although this could be a separate tutorial. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/README.md b/src/content/docs/Splashkit/Tutorials/Reviews/README.md new file mode 100644 index 00000000..46ff33f4 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/README.md @@ -0,0 +1,11 @@ +# Place your tutorials review within this folder + +When doing a tutorial review ensure to do the following: + +- Proof read the tutorial to make sure there are no grammatical errors. +- Ensure the tutorial has the following languages: + - C++ + - C# (with both top level statements and object-oriented tabs) + - Python +- Run all the code in the way the tutorial describes to ensure it works. +- Include screenshots of all the code running in your pull request description. diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/Utilities-guides/useful-utilities.md b/src/content/docs/Splashkit/Tutorials/Reviews/Utilities-guides/useful-utilities.md new file mode 100644 index 00000000..d09a2b59 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/Utilities-guides/useful-utilities.md @@ -0,0 +1,34 @@ +# Useful Utilities + +Date Reviewed: 28-08-2024 + +Reviewed by: Oliver Exell-Bruce + +## Description + +This tutorial covers some of the utilities that splashkit has. The tutorial goes over converting +strings to numbers, checking if a string is a number, and manipulating strings. + +The guide had a couple bugs and some variable names that were inconsistent between languages which +have been fixed. + +## Confirmation of Passing Quality Checks + +- [x] The tutorial is free of spelling and grammatical errors. +- [x] The tutorial is easy to follow. +- [x] The tutorial has: + - [x] C# using top level statements + - [x] C++ + - [x] Python +- [x] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](https://splashkit.io/guides/utilities/0-useful-utilities/) +- [Pull Request](https://github.com/thoth-tech/splashkit.io-starlight/pull/176) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- No suggestions diff --git a/src/content/docs/Splashkit/Tutorials/Reviews/template.md b/src/content/docs/Splashkit/Tutorials/Reviews/template.md new file mode 100644 index 00000000..610a9a75 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/Reviews/template.md @@ -0,0 +1,30 @@ +# Title + +Date Reviewed: + +Reviewed by: + +## Description + +This tutorial covers how to do this... + +## Confirmation of Passing Quality Checks + +- [ ] The tutorial is free of spelling and grammatical errors. +- [ ] The tutorial is easy to follow. +- [ ] The tutorial has: + - [ ] C++ + - [ ] C# (with both top level statements and object-oriented tabs) + - [ ] Python +- [ ] The code passes all the Quality Checks. + +## Links + +- [Tutorial Link](add-link-here) +- [Pull Request](add-link-here) + +## Improvements and suggestions + +If you have any suggestions for improvements or changes, add here: + +- add here diff --git a/src/content/docs/Splashkit/Tutorials/overview.md b/src/content/docs/Splashkit/Tutorials/overview.md new file mode 100644 index 00000000..7b533381 --- /dev/null +++ b/src/content/docs/Splashkit/Tutorials/overview.md @@ -0,0 +1,13 @@ +# SplashKit Tutorials Team + +The SplashKit tutorials team is dedicated to creating high-quality tutorials that showcase the +versatile functionality of the SplashKit library. Covering a broad range of topics such as Graphics, +Interfaces, Networking, and Raspberry Pis, these tutorials are designed to equip users with the +skills needed to develop their own projects. Each tutorial includes detailed explanations, +step-by-step instructions, and code snippets in C#, C++, Python, and Pascal to cater to a diverse +audience. + +The SplashKit website will feature these tutorials, with a focus on helping students learn and +explore SplashKit’s capabilities. Emphasising smaller, high-quality tutorials across C++, C#, and +Python, the aim is to provide concise, yet comprehensive learning resources rather than extensive +series, ensuring that users can quickly grasp and apply the concepts in their own projects. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/linux/README.md b/src/content/docs/Splashkit/Website/Troubleshoot/linux/README.md new file mode 100644 index 00000000..ee8878d9 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/linux/README.md @@ -0,0 +1,9 @@ +![](https://i.imgur.com/pbIntVv.png) + +

SplashKit Installation Solutions (For Mac users)

+This repository provides solutions to known installation issues encountered by Mac users while installing SplashKit. If you are facing any problems with SplashKit, refer to this document for possible solutions. + +## Table of Contents + +- [Issue 1:](linux-issue-1.md) "`bash: skm command not found`" +- [Issue 2:](linux-issue-2.md) "`bash: dotnet command not found`" diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/linux/linux-issue-1.md b/src/content/docs/Splashkit/Website/Troubleshoot/linux/linux-issue-1.md new file mode 100644 index 00000000..bb0c4a17 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/linux/linux-issue-1.md @@ -0,0 +1,58 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Linux

+ +## “`skm: command not found`”: + +## Solutions: + +**Verify installation:** _Check if the SKM executable is present in the .splashkit directory by +running the following command:_ + +```shell +ls -l .splashkit +``` + +![Screenshot](https://i.imgur.com/Rj6RtnH.png) _This will list the contents of the .splashkit +directory, including the SKM executable._ + +1. **Solution 1:** + + If the skm executable is present, you can add it to your system's PATH by running the following + command: + + ```shell + echo 'export PATH="$HOME/.splashkit:$PATH"' >> ~/.bashrc + ``` + + Refresh the environment variables: + + ```shell + source ~/.bashrc + ``` + +1. **Solution 2:** + + Open the .bashrc file: + + ```shell + nano ~/.bashrc + ``` + + Add the following lines at the end of the file: + + ```shell + export LD_LIBRARY_PATH=/usr/local/lib + export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig + ``` + + Save the file and exit the editor (`Ctrl+X`, then `Y`, then `Enter`). + + Refresh the environment variables: + + ```shell + source ~/.bashrc + ``` diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/linux/linux-issue-2.md b/src/content/docs/Splashkit/Website/Troubleshoot/linux/linux-issue-2.md new file mode 100644 index 00000000..7029dd4b --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/linux/linux-issue-2.md @@ -0,0 +1,90 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Linux

+ +## “`bash: dotnet command not found`”: + +![](https://i.imgur.com/tD5BUgD.png) + +## Solution: + +Check if .NET Core SDK is installed: Open a terminal and run the following command: + +```shell +dotnet --version +``` + +If you see the version number, it means that .NET Core SDK is already installed. Ifnot, proceed to +the next step. + +Install .NET Core SDK: To install the .NET Core SDK on Linux, you can follow the official Microsoft +documentation for your specific Linux distribution. Here's a general guide: + +## Ubuntu/Debian: + +```shell +wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb +``` + +```shell +sudo dpkg -i packages-microsoft-prod.deb +``` + +```shell +sudo apt-get update +``` + +```shell +sudo apt-get install -y apt-transport-https +``` + +```shell +sudo apt-get update +``` + +```shell +sudo apt-get install -y dotnet-sdk-7.0 +``` + +## CentOS/Fedora: Copy + +```shell +sudo rpm -Uvh https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm +``` + +```shell +sudo dnf update +``` + +```shell +sudo dnf install dotnet-sdk-7.0 +``` + +Other distributions: Refer to the official Microsoft documentation for instructions specific to your +distribution. Configure the PATH environment variable: After installing the .NET Core SDK, you need +to ensure that the dotnet command is accessible from anywhere on your system. To do this, add the +following line to your shell profile file (e.g., ~/.bashrc, ~/.zshrc): + +```shell +export PATH="$PATH:$HOME/.dotnet" +``` + +Save the file and run the following command to apply the changes: + +```shell + source ~/.bashrc +``` + +or + +```.bash + source ~/.zshrc +``` + +After completing these steps, you should be able to use the dotnet command without encountering the +**"dotnet command not found"** error on Linux. + +![](https://i.imgur.com/Xz3R5v5.png) diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/README.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/README.md new file mode 100644 index 00000000..24b52153 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/README.md @@ -0,0 +1,18 @@ +![](https://i.imgur.com/pbIntVv.png) + +

SplashKit Installation Solutions (For Mac users)

+This repository provides solutions to known installation issues encountered by Mac users while installing SplashKit. If you are facing any problems with SplashKit, refer to this document for possible solutions. + +## Table of Contents + +- [Issue 1:](mac-issue-1.md) + "`bash <(curl -s https://raw.githubusercontent.com/splashkit/skm/master/installscripts/skm-install.sh)`" + does nothing +- [Issue 2:](mac-issue-2.md) "`brew cask install dotnet-sdk`" command not working (or any issues + installing Homebrew) +- [Issue 3:](mac-issue-3.md) "`ln -s /usr/local/share/dotnet/dotnet /usr/local/bin`" command not + working +- [Issue 4:](mac-issue-4.md) "`System.DllNotFoundException unable to load DLL splashkit.dll`" when + trying to run program +- [Issue 5:](mac-issue-5.md) "`zsh: command not found: skm`" +- [Issue 6:](mac-issue-6.md) Error that mentions "(`are you missing an assembly reference?`)" diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-1.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-1.md new file mode 100644 index 00000000..b1ef1627 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-1.md @@ -0,0 +1,31 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : MacOS

+ +## "`bash <(curl -s https://raw.githubusercontent.com/splashkit/skm/master/install-scripts/skm-install.sh)`" does nothing: + +![](https://i.imgur.com/BD8jqnT.png) + +## Solutions + +1. **Solution 1:** + + Make sure you are connected to the internet. + +1. **Solution 2:** + + Disable your computer’s firewall. + +1. **Solution 3:** Go to this URL: + [here](https://github.com/splashkit/skm/blob/master/install-scripts/skm-install.sh) Then click + the “Download raw file” button shown below (where the red arrow is pointing to): + + ![](https://i.imgur.com/MWhWHRO.png) + + Then open Finder to wherever you saved it. In the Terminal, type and then drag and drop the file + from Finder into the Terminal window: + + ![](https://i.imgur.com/LTCf6qW.png) diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-2.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-2.md new file mode 100644 index 00000000..c846bb0c --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-2.md @@ -0,0 +1,24 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : MacOS

+ +## “`brew cask install dotnet-sdk`” command not working (or any issues installing Homebrew): + +
+ +## Solution: + +The corrected command is: + +```shell +brew install dotnet-sdk --cask +``` + +Or alternatively, you can download .NET 7.0 from the +[Microsoft website](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) and click on the macOS +installer link. + +**Note**: Arm64 is used for M1 chips onwards, and x64 is used for Intel based chips. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-3.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-3.md new file mode 100644 index 00000000..86a4db43 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-3.md @@ -0,0 +1,27 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : MacOS

+ +## “`ln -s /usr/local/share/dotnet/dotnet /usr/local/bin`” command not working: + +![](https://i.imgur.com/MJgfrXW.png) + +## Solution: + +Run the following command, and then enter your password: + +```shell +sudo ln -s /usr/local/share/dotnet/dotnet /usr/local/bin +``` + +_The `sudo` command temporarily gives you system (root) privileges._ + +**Note:** If you get a “`zsh: permission denied: dotnet`” error at any point, open Finder and +navigate to the “`/usr/local/bin`” folder. (_You can do this by clicking “Go” at the top of the +screen, then click on “Go to Folder…” and type the folder path here._) + +Delete the “`dotnet`” file in that folder, and then run the command shown at the top of this +Solution in a new Terminal window. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-4.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-4.md new file mode 100644 index 00000000..96d14063 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-4.md @@ -0,0 +1,37 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : MacOS

+ +## “`System.DllNotFoundException unable to load DLL splashkit.dll`” when trying to run program + +## Solutions: + +1. **Solution 1:** Make sure your macOS is fully updated to the latest software if possible (at + least version **12.0** or later). + +2. **Solution 2:** For older macOS versions (**pre-12.0**), you can use the following commands in + the terminal to change SplashKit to a previous version (run each line separately): + + ```shell + cd ~/.splashkit + ``` + + ```shell + git fetch –unshallow + ``` + + ```shell + git checkout cbb68dc + ``` + + Note: Using `skm dotnet new` after these commands might change the way that the SplashKit project + files are created, so you can use this + [**Template SplashKit project**](https://deakin365-my.sharepoint.com/:u:/g/personal/o_mckeon_deakin_edu_au/EZWAVnpc1QxHqFB7KbZ-j_sBreJCSEJLomdDUKsnT7DykA?e=EKefqK) + (_zipped folder_) to create new projects instead of using `skm dotnet new`: + + **Note**: Read the “`README.txt`” file for instructions on how to use the template for new + projects. There is also a comment in `Program.cs` file to help with this, and then you can remove + these commented lines. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-5.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-5.md new file mode 100644 index 00000000..4a4ebc99 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-5.md @@ -0,0 +1,42 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : MacOS

+ +## “`zsh: command not found: skm`”: + +![](https://i.imgur.com/Qv8RaHc.png) + +## Solution: + +Add the `.splashkit` folder to your .zshrc file. The `.zshrc` file is located in +“`~/Users/(your username)/`”. + +_Replace "(your username)" with your username._ Note: You can get your username using the `whoami` +command in the Terminal as shown below: + +![](https://i.imgur.com/Le4nSdA.png) + +You might need to show hidden files. Hold down the shift and command keys, and then press the +`. key (period/dot)` to toggle showing hidden files. + +Open the `.zshrc` file and add the following line: + +```shell +export PATH="$HOME/.splashkit:$PATH" +``` + +As an added precaution for dotnet, you can also add this line to the same file: + +```shell +export PATH="/usr/local/share/dotnet:$PATH" +``` + +And while you are adding to this file, you can also add the following line, which will allow you to +use the command `code .` to open Visual Studio Code from your terminal: + +```shell +export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin" +``` diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-6.md b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-6.md new file mode 100644 index 00000000..fc9d30a1 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/macOS/mac-issue-6.md @@ -0,0 +1,17 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : MacOS

+ +## Error that mentions “(`are you missing an assembly reference?`)”: + +![](https://i.imgur.com/IE0qHXu.png) + +## Solution: + +If your project is called SplashKit, choose a different name for it. + +**Note:** The project name is created from the name of the folder where you are creating the +SplashKit project. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/README.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/README.md new file mode 100644 index 00000000..5003cdbc --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/README.md @@ -0,0 +1,21 @@ +![](https://i.imgur.com/pbIntVv.png) + +

SplashKit Installation Solutions (For Windows users)

+ +_This repository provides solutions to known installation issues encountered by Windows users while +installing SplashKit. If you are facing any problems with SplashKit, refer to this document for +possible solutions._ + +## Table of Contents + +- [Issue 1](win-issue-1.md): + "`bash <(curl -s https://raw.githubusercontent.com/splashkit/skm/master/installscripts/skm-install.sh)`" + does nothing +- [Issue 2](win-issue-2.md): "`System.DllNotFoundException unable to load DLL splashkit.dll`" when + trying to run program +- [Issue 3](win-issue-3.md): "`-bash: skm: command not found`" +- [Issue 4](win-issue-4.md): `Unable to find the .NET SDK` +- [Issue 5](win-issue-5.md) : "`dotnet: command not found`" +- [Issue 6](win-issue-6.md) : Error that mentions "(`are you missing an assembly reference?`)" + +- [Update System path](update-system-path.md) Guide: Update Environment System path diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/update-system-path.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/update-system-path.md new file mode 100644 index 00000000..3e1bf821 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/update-system-path.md @@ -0,0 +1,34 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +## Update your system “Path” variable: + +Steps to add to the "Path" environment variable: + +1. Search for "environment variables" using the search on the task bar: + + ![](https://i.imgur.com/i3cb9nr.png) + + (**Note:** Red box - this might look like a text box for you, Yellow box - you should only have + to type "`env`", then Green box - That's what you click on.) + +1. Under the "`Advanced`" Tab (Red box), click on "`Environment variables`" (Green box): + + ![](https://i.imgur.com/4Cbmnja.png) + +1. Click on "`Path`" (Red box), then click "`Edit`" (Green box): + + ![](https://i.imgur.com/e4H9XIF.png) + + **Note about finding username (for Next Steps):** You can look through your folders in file + explorer to get your username if needed, or use the command in the terminal as shown below: + ![](https://i.imgur.com/2neJLOs.png) + + **_(Step 4 on next page – This is just a step showing the 3 required paths for SplashKit)_** + +1. In the “Edit environment variable” window, you should have the following paths shown in the + Green box (using your own username): ![](https://i.imgur.com/AvNrlNV.png) Once you have these + paths, click “OK” on all the windows, open a new MINGW64 terminal and try running the program + again. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-1.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-1.md new file mode 100644 index 00000000..e6049532 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-1.md @@ -0,0 +1,40 @@ +--- + +title: FAQs on Splashkit installation tags: faq,error,troubleshoot + +--- + +

Issue : Windows

+ +## "`bash <(curl -s https://raw.githubusercontent.com/splashkit/skm/master/install-scripts/skm-install.sh)`" does nothing: + +![](https://i.imgur.com/c6ejBFS.png?1) + +## Solutions + +1. Solution 1: + + Make sure you are connected to the internet. + +1. Solution 2: + + Disable your computer’s firewall. + +1. Solution 3: Go to this URL: + [here](https://github.com/splashkit/skm/blob/master/install-scripts/skm-install.sh) + + Then click the “Download raw file” button shown below (where the red arrow is pointing + to) and save it to somewhere like the Downloads folder: + + ![](https://i.imgur.com/MWhWHRO.png) + + Then open File Explorer to wherever you saved it. + + In the MINGW64 terminal, type `bash` and then drag and drop the file from File Explorer into the + terminal window: + + ![](https://i.imgur.com/ZbcghXz.png) + + Press "`Enter`" and that should run the script. That will install skm, and you can carry on in the + + tutorial from after the "`bash <( curl -s....)`" step. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-2.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-2.md new file mode 100644 index 00000000..bf89a700 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-2.md @@ -0,0 +1,65 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Windows

+ +## `System.DllNotFoundException unable to load DLL splashkit.dll` when trying to run program: + +![](https://i.imgur.com/uEz1nxT.png) + +## Solutions: + +1. **Solution 1:** + + Disable any antivirus software on your computer. + +1. **Solution 2:** + + Make sure your project isn't called "SplashKit". + +1. **Solution 3:** + + Make sure you are creating your project using the MINGW64 terminal (rather than the MSYS + + terminal) and create the project files in its own directory/folder. + +1. **Solution 4:** Add the folder containing splashkit.dll file to your path environment variable + manually. Firstly, go through Steps 1 – 3 shown in the “Update your system “Path” variable” + section [here](update-system-path.md). + + Then come back here for the Next Step. + + **Next Step:** In the “Edit environment variable” window, you should have these two paths shown + in the image below (Green Box) – on the next page + + ![](https://i.imgur.com/lTzyRSo.png) + + If you are missing one of the paths in the Green box, click "New" (Red box), then add the path + you are missing. It will be similar to what is shown in the Green box - just using your own + username. + + Once it is added, click “OK” on all the windows, open a **new** MINGW64 terminal and try running + the program again. + +1. **Solution 5 (if all else fails):** Get it working by copying the SplashKit binaries to the + build output: The SplashKit binaries are in + + `C:\msys64\home\(your username)\.splashkit\lib\win64` + *Replace "(your username)" with your username. (See Note about “whoami” above to get + + your username.)\* + + The contents of the folder should look something like this: + + ![](https://i.imgur.com/XRha19P.png) + + Copy all of these into the build output of your SplashKit project. + This will usually be: + + `\bin\Debug\net7.0` + + *eg, if the folder name is MyProject, and you are using .NET 7.0, it would be:* + + `MyProject\bin\Debug\net7.0` diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-3.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-3.md new file mode 100644 index 00000000..3ca6e455 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-3.md @@ -0,0 +1,28 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Windows

+ +## `-bash: skm: command not found`: + +![](https://i.imgur.com/PMDiueq.png?1) + +## Solution: + +Firstly, go through Steps 1 – 3 shown in the “Update your system “Path” variable” section +[here](update-system-path.md) + +Then come back here for the Next Step. Disable any antivirus software on your computer. + +**Next Step:** In the “Edit environment variable” window, you should have these two paths shown in +the image below (Green Box): + +![](https://i.imgur.com/H9sF33y.png) + +If you are missing one of the paths in the Green box, click "New" (Red box), then add the path you +are missing. It will be similar to what is shown in the Green box - just using your own username. + +Once it is added, click “OK” on all the windows, open a **new** MINGW64 terminal and tryrunning the +program again. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-4.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-4.md new file mode 100644 index 00000000..b79c720e --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-4.md @@ -0,0 +1,25 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Windows

+ +## `Unable to find the .NET SDK:`: + +![](https://i.imgur.com/sjzZGQa.png) + +**Solution :** You might need to add the dotnet folder path to your “Path” environment variable. + +Firstly, go through Steps 1 – 3 shown in the “Update your system “Path” variable” section +[here](update-system-path.md) + +Then come back here for the Next Step. + +**Next Step:** In the “Edit environment variable” window, click "New" (Red box), then add the path +shown in the Green box: + +![](https://i.imgur.com/T6wIBWt.png) + +Once it is added, click “OK” on all the windows, open a **new** MINGW64 terminal and try running the +program again. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-5.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-5.md new file mode 100644 index 00000000..faa0322c --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-5.md @@ -0,0 +1,24 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Windows

+ +## “`dotnet: command not found`”: + +![](https://i.imgur.com/gzi30bu.png) + +## Solution : + +You might need to add the dotnet folder path to your “Path” environment variable. Firstly, go +through Steps 1 – 3 shown in the “Update your system “Path” variable” section +[here](update-system-path.md). + +Then come back here for the Next Step. **Next Step:** In the “Edit environment variable” window, +click "New" (Red box), then add the path shown in the Green box: + +![](https://i.imgur.com/T6wIBWt.png) + +Once it is added, click “`OK`” on all the windows, open a **new** MINGW64 terminal and try running +the program again. diff --git a/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-6.md b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-6.md new file mode 100644 index 00000000..635eca13 --- /dev/null +++ b/src/content/docs/Splashkit/Website/Troubleshoot/windows/win-issue-6.md @@ -0,0 +1,17 @@ +--- +title: FAQs on Splashkit installation +tags: faq,error,troubleshoot +--- + +

Issue : Windows

+ +## Error that mentions “(`are you missing an assembly reference?`)”: + +![](https://i.imgur.com/2W23AI2.png) + +## Solution : + +If your project is called SplashKit, choose a different name for it. + +**Note:** The project name is created from the name of the folder where you are creating the +SplashKit project in your terminal. diff --git a/src/content/docs/Splashkit/Website/WSL installation/README.md b/src/content/docs/Splashkit/Website/WSL installation/README.md new file mode 100644 index 00000000..11fb2076 --- /dev/null +++ b/src/content/docs/Splashkit/Website/WSL installation/README.md @@ -0,0 +1,137 @@ +![](https://i.imgur.com/pbIntVv.png) + +

Splashkit SDK Installation Guide (WSL)

+ +_This guide provides step-by-step instructions for installing the Splashkit SDK through WSL (Windows +Subsystem for Linux). The Splashkit SDK allows you to develop cross-platform applications using C++, +C#, and more._ + +## Prerequisite + +Before you begin, make sure you have the following: + +1. Windows 10+ operating system +2. WSL (Windows Subsystem for Linux) + [prerequisites](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites) +3. Internet connection + +## Installation + +1. **Install WSL** + + _Open the Microsoft Store and search for "WSL"._ _Choose the Linux distribution you prefer (e.g., + Ubuntu, Debian, or openSUSE) and install it._ ![](https://i.imgur.com/6jYdhsO.png) + _Alternatively, open PowerShell (admin) and enter the following script:_ + + ```shell + wsl --install + ``` + +2. **Launch WSL:** _Once WSL is installed, launch the WSL distribution you installed. This will open + a terminal window running a Linux environment._ + +3. **Update the Linux distribution:** + + _In the WSL terminal, run the following commands to update the package lists and upgrade the + installed packages:_ + + ```shell + sudo apt update + sudo apt upgrade + ``` + +4. **Install necessary dependencies:** + + _In the WSL terminal, run the following command to install Git and Curl:_ + + ```shell + sudo apt install git curl + ``` + + ![](https://i.imgur.com/ZKXjGyV.png) + + **[OPTIONAL]** _Install additional dependencies required by Splashkit:_ + + ```shell + sudo apt install build-essential libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev + + ``` + +5. **Download and install Splashkit using SKM (Splashkit Manager):** _In the WSL terminal, run the + following command to download and install Splashkit using the SKM installation script:_ + + ```shell + bash <(curl -s https://raw.githubusercontent.com/splashkit/skm/master/install-scripts/skm-install.sh) + + ``` + +6. **Verify installation:** _Check if the SKM executable is present in the .splashkit directory by + running the following command:_ + + ```shell + ls -l .splashkit + ``` + + ![Screenshot](https://i.imgur.com/Rj6RtnH.png) _This will list the contents of the .splashkit + directory, including the SKM executable._ + +7. **Add SKM to system's PATH:** + ```shell + echo 'export PATH="$HOME/.splashkit:$PATH"' >> ~/.bashrc + source ~/.bashrc + ``` + ![](https://i.imgur.com/s0XAzJw.png) +8. Install SKM tools for Linux **[Optional]** _In the WSL terminal, you can install additional SKM + tools for Linux by running the following command:_ + + ```shell + skm linux install + ``` + + ![](https://i.imgur.com/JtAFvq5.png) + + **Note:** This installation requires approximately 508 MB of disk space.


+ +## Test SKM + +Execute skm to test it was successfully installed. + +```shell + skm +``` + +You should see the following messages: + +```shell +Splashkit is installed successfully! +Missing skm command. For help use 'skm help' +``` + +SplashKit supports a number of languages. Run `skm help` at the terminal to see the different +commands you can run.


+ +## Testing a C++ program + +To test your Splashkit gcc/clang++ compiler, you can use the following C++ program: + +```cpp + #include +int main() { + std::cout << "Hello, World!" << std::endl; + return 0; +} +``` + +Run this by executing the following command in WSL terminal: + +```shell +skm clang++ .cpp -o +./ +``` + +Change the **** and **** with your file names. + +## Acknowledgements + +- [WSL installation](https://learn.microsoft.com/en-us/windows/wsl/install) +- [SplashKit SDK](https://splashkit.io/)