diff --git a/.github/workflows/mastermind.yml b/.github/workflows/mastermind.yml index e9b1f90..d0b0681 100644 --- a/.github/workflows/mastermind.yml +++ b/.github/workflows/mastermind.yml @@ -1,5 +1,18 @@ name: CI for ICS4U Culminating Project Mastermind -on: [push] + +on: + push: + branches: ["main"] + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + jobs: unit-tests: runs-on: ubuntu-latest @@ -11,3 +24,40 @@ jobs: run: | cd culminating-mastermind ./gradlew test + + gh-pages: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Set Up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.4.1" + bundler-cache: true + cache-version: 0 + + - name: Checkout + uses: actions/checkout@v4 + + - name: Build with Jekyll + run: | + cd culminating-mastermind/docs + bundle install + bundle exec jekyll build + env: + JEKYLL_ENV: production + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: culminating-mastermind/docs/_site + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/culminating-mastermind/README.md b/culminating-mastermind/README.md index 5937ea9..76d395d 100644 --- a/culminating-mastermind/README.md +++ b/culminating-mastermind/README.md @@ -1,129 +1,3 @@ -# Mastermind Project Wiki +# Mastermind -## Project Structure - -```tree -. -├── app -│   ├── bin -│   ├── build -│   └── src -│   ├── main -│   │   ├── java -│   │   │   └── mastermind -│   │   │   ├── core -│   │   │   │   └── solvers -│   │   │   ├── gui -│   │   │   │   ├── panels -│   │   │   │   └── scenes -│   │   │   └── utils -│   │   └── resources -│   └── test -│   ├── java -│   │   └── mastermind -│   └── resources -├── build -└── gradle -``` - -### Build Directories - -- `app/bin` -- `app/build` -- `build` - -### Gradle Directory - -- `gradle` - -### Project Sources - -- `app/src/main/java/mastermind/core` core (non-gui) components of program -- `app/src/main/java/mastermind/core/solvers` algorithms for solving mastermind game -- `app/src/main/java/mastermind/gui` gui components of program -- `app/src/main/java/mastermind/gui/panels` shareable gui components -- `app/src/main/java/mastermind/gui/scenes` scenes/stages/pages/screens of the game - - each page/stage/screen of the program is a scene - - e.g., game mode selector, code breaker gameplay, code maker gameplay -- `app/src/main/java/mastermind/utils` general utilities that are not directly - associated with program logic - - i.e., components that can be reused by other projects - - e.g., helper methods, data structures - -### Unit Tests - -- `app/src/test/java/mastermind` - -## Solvers - -```mermaid -classDiagram - MastermindSolver <|-- HumanSolver - MastermindSolver <|-- MastermindAlgorithm - MastermindAlgorithm <|-- EasyAlgorithm - MastermindAlgorithm <|-- MediumAlgorithm - MastermindAlgorithm <|-- DonaldKnuthAlgorithm - - class MastermindSolver { - <> - +getattempts(): int - #isInitialguess(): boolean - #hasExeededMaxGuesses(): boolean - } - - class MastermindAlgorithm { - <> - +guess(): Code* - +guess(response: Response): ~Status, Code~* - } -``` - -## Scenes (GUI) - -Each scene inherits `src/gui/scenes/Scene.java`. - -### Transitions - -Note that the node names correspond to classes in `src/gui/scenes`. - -```mermaid -flowchart TB - mode_select --> algorithm_select - mode_select --> code_maker - - algorithm_select --> code_breaker - - code_maker --> result - code_breaker --> result - - mode_select[GameModeSelector] - result[Result] - - subgraph code breaker - algorithm_select[CodeBreakerSelector] - code_breaker[CodeBreaker] - end - - subgraph code maker - code_maker[CodeMaker] - end -``` - -## Communications Between Solvers and GUI - -### Algorithmic Solvers - -```mermaid -sequenceDiagram - solver ->> gui: first guess - gui ->> solver: user response (hints) - solver ->> gui: next guess -``` - -### Human Solver - -```mermaid -sequenceDiagram - gui ->> solver: user guess - solver ->> gui: response (hints) -``` +Please see [project wiki](https://powersagitar.github.io/ics4u). diff --git a/culminating-mastermind/docs/.editorconfig b/culminating-mastermind/docs/.editorconfig new file mode 100644 index 0000000..236abae --- /dev/null +++ b/culminating-mastermind/docs/.editorconfig @@ -0,0 +1,2 @@ +[*.md] +max_line_length = 80 diff --git a/culminating-mastermind/docs/.gitignore b/culminating-mastermind/docs/.gitignore new file mode 100644 index 0000000..27517b9 --- /dev/null +++ b/culminating-mastermind/docs/.gitignore @@ -0,0 +1,6 @@ +_site +.sass-cache +.jekyll-cache +.jekyll-metadata +Gemfile.lock +vendor diff --git a/culminating-mastermind/docs/404.html b/culminating-mastermind/docs/404.html new file mode 100644 index 0000000..086a5c9 --- /dev/null +++ b/culminating-mastermind/docs/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/culminating-mastermind/docs/Gemfile b/culminating-mastermind/docs/Gemfile new file mode 100644 index 0000000..d8e5ec6 --- /dev/null +++ b/culminating-mastermind/docs/Gemfile @@ -0,0 +1,36 @@ +source "https://rubygems.org" +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +# gem "jekyll", "~> 4.3.4" +# This is the default theme for new Jekyll sites. You may change this to anything you like. +# gem "minima", "~> 2.5" + +gem "just-the-docs" +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +gem "github-pages", "~> 232", group: :jekyll_plugins + +# If you have any plugins, put them here! +group :jekyll_plugins do + gem "jekyll-feed", "~> 0.12" +end + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", ">= 1", "< 3" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin] + +# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem +# do not have a Java counterpart. +gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby] diff --git a/culminating-mastermind/docs/_config.yml b/culminating-mastermind/docs/_config.yml new file mode 100644 index 0000000..2f07fd3 --- /dev/null +++ b/culminating-mastermind/docs/_config.yml @@ -0,0 +1,61 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. +# +# If you need help with YAML syntax, here are some quick references for you: +# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml +# https://learnxinyminutes.com/docs/yaml/ +# +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. + +title: Mastermind Wiki +email: 350877700@gapps.yrdsb.ca + +description: >- # this means to ignore newlines until "baseurl:" + Project wiki for Mastermind, the ICS4U culminating project. + +baseurl: "/ics4u" # the subpath of your site, e.g. /blog +url: "https://powersagitar.github.io" # the base hostname & protocol for your site, e.g. http://example.com + +permalink: pretty + +# twitter_username: jekyllrb +github_username: powersagitar + +# Build settings +theme: just-the-docs + +mermaid: + version: 11.4.1 + +plugins: + - jekyll-feed +# Exclude from processing. +# The following items will not be processed, by default. +# Any item listed under the `exclude:` key here will be automatically added to +# the internal "default list". +# +# Excluded items can be processed by explicitly listing the directories or +# their entries' file path in the `include:` list. +# +# exclude: +# - .sass-cache/ +# - .jekyll-cache/ +# - gemfiles/ +# - Gemfile +# - Gemfile.lock +# - node_modules/ +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/culminating-mastermind/docs/building.md b/culminating-mastermind/docs/building.md new file mode 100644 index 0000000..9f6a067 --- /dev/null +++ b/culminating-mastermind/docs/building.md @@ -0,0 +1,53 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +nav_order: 3 +--- + +# Building the Project + +This project is built using [Gradle](https://gradle.org), with Gradle wrapper +bundled. + +From this point on, you are assumed to be in [project root](http://powersagitar.github.io/ics4u/#project-root) +and using the terminal, and on a UNIX or UNIX-like system. + +If you are on Windows, please replace occurrences of `gradlew` with `gradlew.bat`. + +## Compiling the Project + +Run the following command: + +```zsh +./gradlew build +``` + +## Running the Project + +Run the following command: + +```zsh +./gradlew run +``` + +This command invokes [build](#compiling-the-project) automatically. + +## Running Unit Tests + +Run the following command: + +```zsh +./gradlew test +``` + +## Building Project Wiki + +Install [Jekyll](https://jekyllrb.com/docs/installation/). + +Run the following command: + +```zsh +utils/start-local-wiki.sh +``` diff --git a/culminating-mastermind/docs/components-comms.md b/culminating-mastermind/docs/components-comms.md new file mode 100644 index 0000000..7e78ef4 --- /dev/null +++ b/culminating-mastermind/docs/components-comms.md @@ -0,0 +1,27 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +parent: Components +nav_order: 3 +--- + +# Communications Between Core and GUI Components + +## Algorithmic Solvers ↔ GUI + +```mermaid +sequenceDiagram + solver ->> gui: first guess + gui ->> solver: user response (hints) + solver ->> gui: subsequent guesses +``` + +## Human Solver ↔ GUI + +```mermaid +sequenceDiagram + gui ->> solver: user guess + solver ->> gui: response (hints) +``` diff --git a/culminating-mastermind/docs/components-core.md b/culminating-mastermind/docs/components-core.md new file mode 100644 index 0000000..a617027 --- /dev/null +++ b/culminating-mastermind/docs/components-core.md @@ -0,0 +1,81 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +parent: Components +nav_order: 1 +--- + +# Core Components + +Non-GUI components of the program. + +## Code + +Represents a code in the game. Each code is a sequence of 4 colors. + +## Response + +Represents the response to a guess. It contains the number of correct colors and +the number of correct colors in the correct position. + +I.e., the number of black and white pegs. + +## Solvers + +```mermaid +classDiagram + MastermindSolver <|-- HumanSolver + MastermindSolver <|-- MastermindAlgorithm + MastermindAlgorithm <|-- EasyAlgorithm + MastermindAlgorithm <|-- MediumAlgorithm + MastermindAlgorithm <|-- DonaldKnuthAlgorithm + + class MastermindSolver { + <> + +getattempts(): int + #isInitialguess(): boolean + #hasExeededMaxGuesses(): boolean + } + + class MastermindAlgorithm { + <> + +guess(): Code* + +guess(response: Response): ~Status, Code~* + } +``` + +### MastermindSolver + +The ultimate base class. All solvers are derived from this class. + +It defines a few utility methods that are common to all solvers. + +### HumanSolver + +The solver for code maker mode. + +It compares user input against generated secret code and provides hints. + +### MastermindAlgorithm + +The standard interface for all algorithmic solvers. + +It exposes two methods: `guess()` and `guess(response: Response)`, for the first +and subsequent guesses, respectively. + +The GUI depends on above interface to communicate with the solver. + +### DonaldKnuthAlgorithm + +A MastermindAlgorithm implementation that uses Donald Knuth's 5-guess algorithm +to solve the game. + +### MediumAlgorithm + +TODO: description + +### EasyAlgorithm + +TODO: description diff --git a/culminating-mastermind/docs/components-gui.md b/culminating-mastermind/docs/components-gui.md new file mode 100644 index 0000000..e264307 --- /dev/null +++ b/culminating-mastermind/docs/components-gui.md @@ -0,0 +1,85 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +parent: Components +nav_order: 2 +--- + +# GUI Components + +Components related to GUI of the program. + +## Panels + +Reusable GUI components that can be shared across [scenes](#scenes). + +### GameBoard + +A game board that displays state of the game: + +- The guesses, and +- The hints. + +The game board is designed to look like a physical mastermind board. + +### HomeButton + +A home button that navigates to the first scene from any scenes. + +## Scenes + +Different screens of the game. + +E.g., game mode selector, code breaker gameplay, code maker gameplay, etc. + +```mermaid +flowchart TB + mode_select --> algorithm_select + mode_select --> code_maker + + algorithm_select --> code_breaker + + code_maker --> result + code_breaker --> result + + mode_select[GameModeSelector] + result[Result] + + subgraph code breaker + algorithm_select[CodeBreakerSelector] + code_breaker[CodeBreaker] + end + + subgraph code maker + code_maker[CodeMaker] + end +``` + +### GameModeSelector + +Prompts the user to select a game mode: + +- code breaker: the program tries to guess a secret code with algorithms, or +- code maker: the user tries to guess a code that the program generates. + +### CodeBreakerSelector + +Prompts the user to select an algorithm to use for guessing the secret code: + +- Donald Knuth's 5-guess algorithm, or +- Medium algorithm, or +- Basic algorithm. + +### CodeBreaker + +The actual code breaker gameplay. + +### CodeMaker + +The code maker gameplay. + +### Result + +The result screen to display whether the user/program wins/loses. diff --git a/culminating-mastermind/docs/components-utils.md b/culminating-mastermind/docs/components-utils.md new file mode 100644 index 0000000..2024590 --- /dev/null +++ b/culminating-mastermind/docs/components-utils.md @@ -0,0 +1,22 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +parent: Components +nav_order: 4 +--- + +# Utility Components + +General utilities that are not directly associated with program logic. + +I.e., components that can be reused by other projects. + +## MathUtil + +Math utility methods. + +## Tuple2 + +A tuple data structure of two elements. diff --git a/culminating-mastermind/docs/components.md b/culminating-mastermind/docs/components.md new file mode 100644 index 0000000..c9fc8bd --- /dev/null +++ b/culminating-mastermind/docs/components.md @@ -0,0 +1,9 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +nav_order: 4 +--- + +# Components diff --git a/culminating-mastermind/docs/index.md b/culminating-mastermind/docs/index.md new file mode 100644 index 0000000..093a9fa --- /dev/null +++ b/culminating-mastermind/docs/index.md @@ -0,0 +1,21 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: home +nav_order: 1 +--- + +# Home + +The project wiki for ICS4U culminating project, mastermind. + +Please use the sidebar for navigation, and the search bar for quick access to +specific topics. + +## Project Root + +The repository this project resides in is a compilation of all coursework +throughout the semester. + +Thus, the project root is [`/culminating-mastermind`](https://github.com/powersagitar/ics4u/tree/main/culminating-mastermind). diff --git a/culminating-mastermind/docs/project-structure.md b/culminating-mastermind/docs/project-structure.md new file mode 100644 index 0000000..283d384 --- /dev/null +++ b/culminating-mastermind/docs/project-structure.md @@ -0,0 +1,61 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: page +nav_order: 2 +--- + +# Project Structure + +```tree +. +├── app +│   ├── bin +│   ├── build +│   └── src +│   ├── main +│   │   ├── java +│   │   │   └── mastermind +│   │   │   ├── core +│   │   │   │   └── solvers +│   │   │   ├── gui +│   │   │   │   ├── panels +│   │   │   │   └── scenes +│   │   │   └── utils +│   │   └── resources +│   └── test +│   ├── java +│   │   └── mastermind +│   └── resources +├── build +└── gradle +``` + +## Build Directories + +- `app/bin` +- `app/build` +- `build` + +## Gradle Directory + +- `gradle` + +## Project Sources + +- `app/src/main/java/mastermind/core` core (non-gui) components of program +- `app/src/main/java/mastermind/core/solvers` algorithms for solving mastermind game +- `app/src/main/java/mastermind/gui` gui components of program +- `app/src/main/java/mastermind/gui/panels` shareable gui components +- `app/src/main/java/mastermind/gui/scenes` scenes/stages/pages/screens of the game + - each page/stage/screen of the program is a scene + - e.g., game mode selector, code breaker gameplay, code maker gameplay +- `app/src/main/java/mastermind/utils` general utilities that are not directly + associated with program logic + - i.e., components that can be reused by other projects + - e.g., helper methods, data structures + +## Unit Tests + +- `app/src/test/java/mastermind` diff --git a/culminating-mastermind/utils/start-local-wiki.sh b/culminating-mastermind/utils/start-local-wiki.sh new file mode 100755 index 0000000..bdba450 --- /dev/null +++ b/culminating-mastermind/utils/start-local-wiki.sh @@ -0,0 +1,19 @@ +#!/bin/zsh + +which bundle + +if [[ $? -ne 0 ]]; then + echo 'bundle (ruby) must be installed.' +fi + +jekyll_config="docs/_config.yml" + +if [[ ! -f "$jekyll_config" ]]; then + echo 'Please run the script in `culminating-mastermind`.' + exit 1 +fi + +cd docs + +bundle install +bundle exec jekyll serve