Finish v3.0

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "src/engine/wtk"]
-	path = src/engine/wtk
-	url = https://github.com/hsandt/PICO8-WTK.git
+[submodule "pico-boots"]
+	path = pico-boots
+	url = ../pico-boots.git

.travis.yml

@@ -1,42 +1,40 @@
-# https://github.com/mpeterv/hererocks
+os: linux
 
 language: python # Can use any language here, but if it's not 'python'
                  # it becomes necessary to pass '--user' to pip when installing hererocks.
-python:
-  - "3.6"
-
-sudo: false      # Use container-based infrastructure.
-
-os:
-  - linux
+python: "3.6"
 
 env:
-  - LUA="lua 5.3"         BUILD_VERSION="2.3"
+  - LUA_VERSION=5.3 ENABLE_RENDER=1
 
 cache:
-  apt: true  # private repositories only
   directories:
-    - lua5.3  # for hererocks
-    - tool    # remember to "travis cache --delete" from travis CL if p8tool needs upgrade
-    - $HOME/.cache
+    # remember to "travis cache --delete" in travis CL each time a custom cached directory needs upgrade (unlike cached packages)
+    - hererocks     # for hererocks (make a parent folder, then install lua inside, to make sure the folder will be used as cache)
+                    # just a small optimization to cache the whole lua install, since the hererocks pip wheel is cached with .cache/pip anyway
+    - tool          # for picotool
+    - $HOME/.cache  # for .cache/luarocks and .cache/pip
 
 before_install:
   # install hererocks if needed
   - |
-    if [[ ! -d lua5.3 || ! -x lua5.3/bin/activate ]]; then
+    if [[ ! -d lua$LUA_VERSION || ! -x lua$LUA_VERSION/bin/activate ]]; then
       pip install hererocks
-      hererocks lua5.3 --$LUA -rlatest
+      pushd hererocks
+      hererocks lua$LUA_VERSION --lua $LUA_VERSION -rlatest
+      popd
     fi
-  - source lua5.3/bin/activate  # Add directory with all installed binaries to PATH.
+
+  # activate Lua
+  - source hererocks/lua$LUA_VERSION/bin/activate
 
 install:
   # install lua packages for testing
   - luarocks install busted
   - luarocks install luacov
-  # install npm packages for minification
-  - pushd npm
-  - npm update
-  - popd
+
+  # delegate submodule install (for luamin from npm)
+  - pico-boots/setup.sh
 
 before_script:
   # download picotool if needed
@@ -54,18 +52,20 @@ before_script:
   - ln -s "$(pwd)/tool/picotool-master/p8tool" "$HOME/.local/bin/p8tool"
 
 script:
-  # test
-  - ./test.sh all all
+  # test (including rendered headless itests thanks to ENABLE_RENDER=1)
+  - ./test.sh -m all
   # coverage
   - bash <(curl -s https://codecov.io/bash)
-  # build for deploy
-  - ./build.sh main release
+  # build game and itest to make sure everything works fine
+  - ./build_game.sh debug
+  - ./build_game.sh release
+  - ./build_itest.sh
 
 deploy:
   provider: releases
-  api_key: $DEPLOY_API_KEY
-  file: "build/sonic-pico8_v${BUILD_VERSION}_release.p8"
-  skip_cleanup: true
+  api_key:
+    secure: bfXQQ0AXGHgXiq0xOxhYQ2AXX/flQnxJh/+eA/HUGfwdoPDq0QTdqFA/3jEMWkJSsFKEBVKDjJGCt24QPxUIjTu91r1wyCNdL2KlNfnogRjWAVutRZxB/OC2HWR3kJtPjkFQBCsOXHBxGI3hMJL7LWr5WfNsSGMbcRMfvphxFT3ER8XBHAUEJY6roITm6noHroqQt8Uye+0+rkGqJ8QslKRqq8qBZMZeOiOrh6SBdlhsGw0KqNno/dMXQxx2ZCrh/VUeWjNvxzXe/mZjfBPbhvyecN7jz+FytEdAhdt1Dy37hhyOAkDfxLGGsH1YAAfinH8uFwoSRo0MH8fuhdXpT7jUXuAgP9/RS0FEiZDdX+J/FdncCbnoDfE9B4Dt3L3srISeiNwxKK5sx2kzyWvftK30pV1+zEgnbVEKGPIIeGb5wYWSCmzHf+CfLMk+bzeznTrpo/irY/vjoRBefNaVWXqLygrNWxM1uIMJae+OA3MYeUSYd1lpCyRw98i3GC7si68M9OaDeLoDjnqOLqvhurB/RmLzCU7mCYipn2kxykAOdevWN73cyx9VhdFy2GPE5VDw6EO6ZQP04KaeYxP2pgR4ts2kYWpVvf1PGg+2yN4QMkVhrWV+6dG2jtUO0BrCqt5Tpw0I3C3aFmBjjzFBBuKsZpr2yUG3roxnu1Dhww0=
+  file: build/picosonic_v3.0_release.p8
   on:
-    branch: master
-    tags: true
+    tags: 'true'
+  skip_cleanup: 'true'

README.md

@@ -6,13 +6,17 @@ develop
 [![Build Status](https://travis-ci.org/hsandt/sonic-pico8.svg?branch=develop)](https://travis-ci.org/hsandt/sonic-pico8)
 [![codecov](https://codecov.io/gh/hsandt/sonic-pico8/branch/develop/graph/badge.svg)](https://codecov.io/gh/hsandt/sonic-pico8)
 
-# Sonic PICO-8
+# PICO-Sonic
 
-A partial clone of classic Sonic the Hedgehog games made with PICO-8
+A partial clone of classic Sonic the Hedgehog games made with PICO-8. It is inspired by the 16-bit games for mechanics, and by a mix of the 8-bit and 16-bit games for graphics and audio.
+
+This is a fan game distributed for free and is not endorsed by Sega Games Co., Ltd, which owns the Sonic the Hedgehog trademark and retains all copyrights on the original assets.
+
+It is currently under development.
 
 ## Features
 
-Version: 2.3
+Version: 3.0
 
 ### Physics
 
@@ -25,34 +29,25 @@ Version: 2.3
 * Character rendered with Idle and Spin static sprite, Run animated sprite
 * Environment rendered with tilemap
 
-## Build
-
-### Supported platforms
-
-Only Linux Ubuntu (and supposedly the Debian family) is fully supported to build the game from sources. Other Linux distributions and UNIX platforms should be able to run most scripts, providing the right tools are installed, but a few references like `gnome-terminal` in `run.sh` would require adaptation.
+## Releases
 
-Development environments for Windows such as MinGW and Cygwin have not been tested.
+You can directly download a released version of the game on the [releases](Releases) page, and run it with PICO-8 as you would normally with a downloaded cartridge.
 
-### Build dependencies
-
-#### Python 3.6
-
-Prebuild and postbuild scripts are written in Python 3 and use 3.6 features such as formatted strings.
+## Build
 
-#### picotool
+Follow this if you want to build the game yourself.
 
-A build pipeline for PICO-8 ([GitHub](https://github.com/dansanderson/picotool))
+Soon, you will be able to choose between building the debug or the release version.
 
-#### luamin
+### Supported platforms
 
-A Lua minifier ([luamin](https://github.com/mathiasbynens/luamin))
+Mostly UNIX, and specifically Linux for some scripts.
 
-You don't need to install it globally, instead you can:
+See Supported platforms in [pico-boots](https://github.com/hsandt/pico-boots) README for more information.
 
-* `cd npm`
-* `npm update`
+### Build dependencies
 
-It will install `luamin` (along with `luaparse`), which is used in `npm/luamin_file`, itself used inside `build.sh`. `luamin_file` is just a stripped down version of the `luamin` script, which only takes a file path argument, and behaves as if the input always came from a TTY, which avoids stalling while building from a non-terminal environment such as a Sublime Text build system (it's a hack).
+See *Build dependencies* in [pico-boots](https://github.com/hsandt/pico-boots) README.
 
 ### Build and run
 
@@ -61,22 +56,35 @@ First, make sure the `pico8` executable is in your path.
 The most straightforward way to build and run the game on Unix platforms is:
 
 * `cd path/to/sonic-pico8-repo`
-* `./build.sh main release`
-* `./run.sh main release`
+* `./build_game.sh`
+* `./run_game_debug.sh`
 
 Instead of the last instruction, you can also enter directly:
-
-* `pico8 -run build/sonic-pico8_v${BUILD_VERSION}_release.p8`
+* `pico8 -run build/picosonic_v${BUILD_VERSION}_debug.p8`
 
 where BUILD_VERSION is set in `sonic-2d-tech-demo.sublime-project` as well as `.travis.yml`.
 
-`sonic-2d-tech-demo.sublime-project` contains the most used commands for building the game. If you don't use Sublime Text, you won't be able to run the commands directly, but you can use them directly in a terminal, or copy-paste them to the project configuration of your favorite code editor.
+Note, however, that the current debug version is bloated and is likely not to run in a vanilla PICO-8 (due to the cartridge getting over the max token limit).
+
+To play the release version (no debugging features, but more compact code and more likely to fit into a PICO-8 cartridge):
+
+* `cd path/to/sonic-pico8-repo`
+* `./build_game.sh` release
+* `./run_game_release.sh`
+
+### Run integration tests
 
-All the build and run commands are usage variants around the script `build.sh` and `run.sh`. `build.sh` relies on picotool as well as custom shell and Python scripts in the `prebuild` and `postbuild` folders.
+Integration tests consists in game simulations in predetermined scenarios, and are therefore run directly in PICO-8. To build the integration test cartridge and run it:
 
-`build.sh` can take a build configuration as 2nd argument. The complete list of configurations is listed in `sonic-2d-tech-demo.sublime-project` and `prebuild/preprocess.py`. The config of biggest output size is `build` (generally it has too many tokens to even fit in a cartridge), while the config of smallest output size is `release`, and is used to release the final game cartridge.
+* `cd path/to/pico-boots-demo`
+* `./build_itest.sh`
+* `./run_itest.sh`
 
-Finally, `build.sh` takes a file base name as 1st argument. To build the game, passing `main` is enough, but to build rendered integration tests, you need to pass the name of the test, such as `itestplayercharacter`.
+### Custom build
+
+`sonic-2d-tech-demo.sublime-project` contains the most used commands for building the game. If you don't use Sublime Text, you won't be able to run the commands directly, but you can still read this project file to understand how the scripts are used, and do the same in a terminal. You can also copy-paste the commands to the project configuration of your favorite code editor instead.
+
+All the build and run commands revolve around the scripts `build_game.sh` / `build_itest.sh` and `run_game.sh` / `run_itest.sh`. Once you understand them, you can create your own build and run commands for your specific needs.
 
 ## Test
 
@@ -88,34 +96,24 @@ Finally, `build.sh` takes a file base name as 1st argument. To build the game, p
 
 ### Test dependencies
 
-#### Lua 5.3
-
-Tests run under Lua 5.3, although Lua 5.2 should also have the needed features (in particular the bit32 module).
-
-#### busted
-
-A Lua unit test framework ([GitHub](https://github.com/Olivine-Labs/busted))
-
-The test script (`test.sh`) only works on Linux (it uses gnome-terminal).
+See *Test dependencies* in [pico-boots](https://github.com/hsandt/pico-boots) README.
 
 ### Run unit tests and headless integration tests
 
-To test the modules:
-
-* `cd path/to/sonic-pico8-repo`
-* `./test.sh all` or `./test.sh all all` if you want to include `#mute` tests (longer)
+To run all the (non-#mute) unit tests:
 
-This will run all the unit tests, as well as headless integration tests. To only run the latter type, use `./test.sh headless_itests`.
+* `cd path/to/pico-boots-demo`
+* `./test.sh`
 
 I try to aim for 100% test coverage before pushing but you can always verify the Travis and CodeCov badges at the top of this README.
 
 ### Run rendered integration tests
 
-Those tests need to be built with picotool and run with PICO-8. We recommend the itest_light config, which has no visual logging but increases the odds to have a build that fits into a cartridge. For example:
+Integration tests consists in actual game simulations in predetermined scenarios. Therefore, they are built with picotool and run directly in PICO-8. To build the integration test cartridge and run it:
 
-* `cd path/to/sonic-pico8-repo`
-* `./build.sh itestplayercharacter itest_light`
-* `./run.sh itestplayercharacter itest_light`
+* `cd path/to/sonic-pico8-demo`
+* `./build_itest.sh`
+* `./run_itest.sh`
 
 ## Modding
 
@@ -131,42 +129,6 @@ Alternatively, to edit the spritesheet in your favorite editor:
 2. Edit it in your favorite editor
 3. Import it back to PICO-8 with the PICO-8 command `import spritesheet.png`
 
-## Development
-
-### Documentation
-
-Most of the documentation lies in code comment.
-
-`<fun1, fun2>` means a duck-typed object that must implement functions named `fun1` and `fun2`
-
-## New project
-
-If you use the scripts of this project to create a new game, in order to use build command `p8tool: edit data` you need to create a pico8 file at data/data.p8 first. To do this, open PICO-8, type `save data`, then copy the boilerplate file to data/data.p8.
-
-## Runtime third-party libraries
-
-### PICO8-WTK
-
-[PICO8-WTK](https://github.com/Saffith/PICO8-WTK) has been integrated as a submodule. I use my own fork with a special branch [cleam\n-lua](https://github.com/hsandt/PICO8-WTK/tree/clean-lua), itself derived from the branch [p8tool](https://github.com/hsandt/PICO8-WTK/tree/p8tool).
-
-* Branch `p8tool` is dedicated to p8tool integration. It exports variables instead of defining global variables to fit the require pattern.
-
-* Branch `clean-lua` is dedicated to replacing PICO-8 preprocessed expressions like `+=` and `if (...)` with vanilla Lua equivalents. Unfortunately we need this to use external testing libraries running directly on Lua 5.3.
-
-## Test third-party libraries
-
-### gamax92/picolove's pico8 API
-
-pico8api.lua contains vanilla lua equivalents or placeholders for PICO-8 functions. They are necessary to test modules from *busted* which runs under vanilla lua. The file is heavily based on gamax92/picolove's [api.lua](https://github.com/gamax92/picolove/blob/master/api.lua) and [main.lua](https://github.com/gamax92/picolove/blob/master/main.lua) (for the `pico8` table), with the following changes:
-
-* Removed console commands (ls, cd, etc.)
-* Removed unused functions
-* Removed wrapping in api table to import functions globally (except for print)
-* Remove implementation for LOVE 2D
-* Adapted to Lua 5.3 instead of LuaJIT (uses bit32 module)
-
-Low-level functions have the same behavior as in PICO-8 (add, del, etc.), whereas rendering functions only simulate the behavior by changing the `pico8` table's state (camera, clip, etc.). Pixels rendered on screen are not simulated though, so the actual effect of rendering cannot be tested.
-
 ## References
 
 * Classic Sonic games (Sonic the Hedgehog, Sonic the Hedgehog 2, Sonic the Hedgehog 3 & Knuckles)
@@ -187,10 +149,6 @@ The `npm` folder has its own MIT license because I adapted a script from the `lu
 
 ### Assets
 
-Most assets are derivative works of Sonic the Hedgehog (SEGA), especially the Master System and Mega Drive games. They have been created, either manually or with a conversion tool, for demonstration purpose. BGMs have been converted from Master System midi rips to PICO-8 format with [midi2pico](https://github.com/gamax92/midi2pico), an automated music format converter.
-
-SEGA owns the Sonic the Hedgehog trademark and retains all copyrights on the original assets.
-
-I only retain copyright for the manual work of adaptation (i.e. pixel art, but not music).
+Most assets are derivative works of Sonic the Hedgehog, especially the Master System and Mega Drive games. They have been created, either manually or with a conversion tool, for demonstration purpose. I drew the sprites based on the Mega Drive and GBA games, while the BGMs have been converted from Master System midi rips to PICO-8 format with [midi2pico](https://github.com/gamax92/midi2pico), an automated music format converter.
 
 Assets that are not derivative works are under CC BY 4.0.