search

elementum-games / shinobi-chronicles

https://shinobichronicles.com
MIT License
12 stars 44 forks source link

readme

Overview

Contributing
Local Setup

Contributing

Feel free to tackle any of the issues at https://github.com/levimeahan/shinobi-chronicles/issues - Assign yourself or drop a comment mentioning you're working on it so others know. You can also drop any questions on the issue to clarify exactly what needs to be done.

You can also create a new issue if there's something you want to add that's not on the list and get the yay/nay from a maintainer on it to avoid building something that's not going to get approved.

Once you've created a pull request, ping @Lsmjudoka on the #sc-coding Discord channel for review.

Large Features

If you want to work on a large feature (either in the Issues tab or not), the recommendation is to write up a proposal with the details (from a gameplay perspective) and post it in the #sc-coding channel on discord, tagging @Lsmjudoka for review. Then the details of the feature and compensation can be agreed upon before work is started.

Recommended workflow

  1. Fork repo on GitHub (top right)
    image

  2. Clone your fork to your local machine (you can find the URL to clone under "Code")
    image

  3. Create a new branch for your changes

  4. Make the changes and test them on your local environment, then commit them to the branch

  5. Push the branch to your forked repo on GH

  6. Open a pull request from your fork/branch to the primary repo (levimeahan/shinobi-chronicles) and main branch

    • There's a "Contribute" button on the main page of your fork you can use to compare and open a pull request image

  7. After pull request is merged (and before starting work on a new feature if it's been more than a day or two) update your local fork from the original repo

    • You can either do this via the command line, or the GitHub UI
    • For command line:
      • First, add a remote of the primary repo to your local clone
      • git remote add upstream https://github.com/levimeahan/shinobi-chronicles.git
      • Then when you want to update your local, run
      • git pull upstream main
    • For GUI
      • Click the "Fetch upstream" prompt on the GitHub page for your fork
      • image
      • Pull the changes from your GitHub fork to your local

Local Setup

You need an environment with four to five things:

You can use any IDE and setup you want if you have the know-how, but this guide lays out one way to get started quickly with minimal PHP environment/Git knowledge.

  1. Fork repo
  2. Download PhpStorm (https://www.jetbrains.com/phpstorm/)
  3. Setup PhpStorm
    • Open from VCS -> GitHub
    • login to your account
    • choose shinobi-chronicles repository from the list
  4. Download XAMPP (https://www.apachefriends.org/index.html)
  5. Setup Apache in XAMPP
    • Go to apache > config > httpd.conf
    • Find DocumentRoot and change the path "C:\xampp\htdocs" to your shinobi-chronicles directory
      • (You can right-click the top folder in PhpStorm after opening it > copy path > absolute path)
    • Change the default path below in <Directory "C:\xampp\htdocs"> to your shinobi-chronicles directory
  6. Setup MySQL in XAMPP
    • Go to MySQL > Admin/PhpMyAdmin > user accounts
    • Go to add user
    • Enter the name shinobi_chronicles and give it a password (doesn't matter what it is, can just be "password") > check "create database with same name and grant all permissions"
  7. Setup game config in PhpStorm
    • Find secure/vars.sample.php
    • Make a copy of it as secure/vars.php
    • Change the values to the ones from your database:
      • user = shinobi_chronicles
      • database = shinobi_chronicles
      • password = (whatever you set as your password)
  8. Install Composer
  9. Use Composer to install important dependencies
    • Open your command line/terminal, navigate to your SC directory, and run composer install
  10. Import the DB using Phinx
    • (Phinx is automatically installed when you run composer install in the previous step)
    • In your command line/terminal, navigate to your SC directory and run
      • vendor/bin/phinx seed:run
    • This will populate your database with all the relevant tables and sample data
  11. Run it
    • First, make sure Apache and MySQL are both started in XAMPP
    • Then navigate to http://localhost/ and you should see the game come up

Installing PHP Manually

Composer

We use composer for managing some dependencies and info about PHP version.

Once installed, navigate to your SC directory in your CLI and run composer install.

Database Migrations

We use Phinx for simple migration management. The documentation on writing migrations is here: https://book.cakephp.org/phinx/0/en/migrations.html

Initial Setup

Quick Cheatsheet

See /db/SampleSQLMigration.php for a simple example of creating a migration that uses raw SQL queries.

Docker compose

To get started you will need to have Docker installed. Easiest way is to install the Docker Desktop app via https://www.docker.com/products/docker-desktop/ Once installed you will need to have the Docker Desktop app running to start the Docker Engine (this isn't needed if you install docker separately)

Notes about Docker Desktop:

This app provides an easy way to see what containers are currently running on your system and what images are downloaded. If you are not using an IDE with built in Docker support (such as PHPStorm) this makes the process a little more GUI driven.

Before starting docker, it's recommended to install dependencies with composer install (step 9 at the beginning of this readme). Otherwise, they'll be re-installed every time you destroy the docker image or upgrade a dependency version.

Update environment variables inside /docker/.env these will be used for the creation of database and automatically updated in the SC Files. Once updated, run the docker stack by running the command docker compose --env-file ./docker/.env up -d

After the stack is built and running, you can navigate to http://localhost/ (default port is 80, this can be modified in the docker compose file) to access the SC game. Additionally, you can navigate to http://localhost:8080 to access phpmyadmin (a sql browser/editor) then log in with the db credentials you provided in the .env file.

NOTICE: The docker stack ALWAYS runs the seed and migrations for the database after start up. This means if you don't create a user after the first startup it's possible the seed will run again.

Installing Required PHP Extensions

This varies by system, but generally:

Windows

Linux
These extensions are usually managed by your package manager, try installing, prefixed with php<version>-. Examples

Ubuntu: sudo apt-get install php8.0-mbstring

CentOS / RedHat: sudo yum install php8.0-mbstring

Note about ext-dom

Node.js and NPM

We use Node.js and NPM to install Javascript packages for some advanced UI interfaces using ReactJS and other libraries, such as the Battle page. (see the ui_components directory for the full list)

If you are not making changes to any of these pages, you do not need to install Node.js and NPM.

Advanced UI Components

Some of the syntax used in these components (e.g. JSX) is not natively available in browsers, so we have to compile the source code into plain JavaScript for it to run in browsers.

PhpStorm file watcher setup

Scope

Testing

You will need to install Composer and run composer install to install the PHPUnit testing framework.

Run composer test to run all tests.

For more on writing tests with PHPUnit, see the docs for PHPUnit here: https://phpunit.readthedocs.io/en/9.5/

Remote Server Setup reference (CentOS 7)

Install PHP 8 CLI

Install dependencies and setup database