README.md

# Free Cities - pregmod

Pregmod is a modification of the original [Free Cities](https://freecitiesblog.blogspot.com/) created by FCdev.

## Play the game

To play the game you have to download the sources first. You can either download an archive of the current state or, if
you plan to keep up to date with current progress, clone the repository.

Clone the repo:

1. [Install Git for terminal](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) or a Git GUI of your choice.
2. Clone the repo
    * Via terminal: `git clone --single-branch https://gitgud.io/pregmodfan/fc-pregmod.git`
3. Get updates
    * Via terminal: `git pull`

Compile the game:

* Windows
    * Run compile.bat
    * Second run of compile.bat will overwrite without prompt

* Linux/Mac
    1. Ensure executable permission on file `devTools/tweeGo/tweego` (not tweego.exe!)
    2. Ensure executable permission on file `compile.sh`
    3. In the root dir of sources (where you see src, devTools, bin...) run command `./compile.sh` from console. 
        Alternatively, if you have make installed, run `make all` in the root directory.

To play open FCpregmod.html in bin/ (Recommendation: Drag it into incognito mode)

## Common problems

* I get an error on gamestart reading `Apologies! A fatal error has occurred. Aborting. Error: Unexpected token @ in 
    JSON at position 0. Stack Trace: SyntaxError: Unexpected token @ in JSON at position 0 at JSON.parse (<anonymous>)
    at JSON.value` or some variant
    - clear cookies

* Everything is broken!
    - Do not copy over your existing download as it may leave old files behind, replace it entirely

* I can't save more than once or twice.
    - Known issue caused by sugarcube level changes. Save to file doesn't have this problem and will likely avoid the first problem as well.
    - It is possible to increase the memory utilized by your browser to delay this

* I wish to report a sanityCheck issue.
    - Great, however a large majority of the results are false positives coming from those specific sections being split
      over several lines in the name of readability and git grep's 
      [intentionally](http://git.661346.n2.nabble.com/bug-git-grep-P-and-multiline-mode-td7613900.html ) lacking support
       for multiline. An Attempt to add -Pzl (https://gitgud.io/pregmodfan/fc-pregmod/merge_requests/2108 ) created a 
       sub condition black hole. What follows are examples of common false positives that can safely be ignored:
```
[MissingClosingAngleBracket]src/art/vector/Generate_Stylesheet.tw:11:<<print "<style>."+_art_display_class+" {
	<<print "<style>."+_art_display_class+" {
position: absolute;
height: 100%;
margin-left: auto;
margin-right: auto;
left: 0;
right: 0;
}
```

## Contribute

First time setup:

0. Follow the steps to clone the main repository if you haven't already.
1. Create an account on gitgud if you don't have a usable one.
    * (optional) Add an SSH key to your account for easier pushing. This allows you to connect to gitgud through SHH, 
    which doesn't require your credentials every time.
2. Fork the main repository through gitgud interface.
    * (optional) Delete all branches other than pregmod-master, so you don't get them locally when fetching.
3. Setup your fork as a remote
    * (optional) Rename the main repository to upstream
        * Via terminal: `git remote rename origin upstream`
    * Add your repo as remote
        * Via terminal: `git remote add origin <url-to-your-fork>`
        * The big clone button in the gitgud interface on your fork gives you the relevant URLs.
4. Checkout `pregmod-master`
    * Via terminal: `git checkout pregmod-master`
5. Make sure `fc-pregmod` tracks `upstream/master`
    * Via terminal: `git branch -u upstream/pregmod-master`

Typical cycle with Git:

1. Get changes from upstream
    * Via terminal: `git pull`
    * If you don't get new commits from `upstream` repeat steps 4&5 of the setup.
2. Checkout a new branch for your work
    * Via terminal: `git checkout -b <branch-name>`
3. Make your changes as you like
4. Commit your changes
    * Via terminal: `git commit <files>`
    * Make the commit message useful (`Fix X`, `Add Y`, etc.)
5. (optional, but recommended) Run sanityCheck before final push to catch any errors you missed. (You can ignore errors unrelated to files you changed.)
6. Push result into your forked repository 
    * Via terminal:
        * Initially `git push -u origin <branch-name>`
        * Afterwards `git push` will suffice.
7. Create merge request through gitgud interface.
8. Checkout `pregmod-master` in preparation of next change.
9. Once the merge request was accepted, delete your local branch.
    * Via terminal: `git branch -d <branch-name>`

## Submodules

FC uses a modified version of SugarCube 2. More information can be found [here](devNotes/sugarcube stuff/building SugarCube.md).