bloatrunner/README.org

* Bloatrunner

A Lode Runner clone where you have to manage your waistline bloat.

![Screenshot of Bloatrunner](assets/images/glamshot.png)

As a *Bloatrunner* you have to collect keys to open the gate at the top
of the level. However running costs energy, and as in any endurance
event energy management and correct fueling is of utmost
importance. By running your glycogen reserves in your muscles will
deplete and need to be replenished either from food or from fat
reserves.

Your running kit has some small pockets to store a few gels or packets
of gummi bears for fast energy replenishment. You will find
replacements from time to time. In addition there will be other food
items distributed over the levels.

However as in real life it seems that most food items are unhealthy
and for some reason irresistable so they are consumed
immediately. Similarly for some reason it seems that food turns
immediately into fat and takes forever to burn off. And too much fat
makes you slow and even worse might make passing the finish gate a
squeeze or plainly impossible.

And then there are the _others_, which for some reason can run without
getting tired, eat without getting fat, voice their judgmental
opinions and generally make a nuisance of themselves. Close contact
with these makes you lose the will to live and turns you into a couch
potato, ceasing to be a _Bloatrunner_.

A freak accident involving some radioactive meteorite allows you to
create craters at will, well, more like potholes. But big enough to
let the _others_ fall in so you can pass over their head.

So now, go out, collect the keys and maintain a healthy diet!


* Game Plan [20/25]

 - [X] start project organization
 - [X] select some assets to start with
 - [X] animate hero 
 - [X] figure out tile maps
 - [X] create hero entity
 - [X] implement hero movement
 - [X] create other entity
 - [X] bundle game for distribution
   - [X] add assets to the package
   - [X] wrap the script to find the libraries
   - [X] ensure the assets can be found by the render packages
 - [X] upload to itch.io
 - [X] automate upload to itch.io
 - [X] create other's AI
 - [X] add keys and portal
 - [X] make other avoid each other
 - [X] ask AI for some boxart 
 - [X] Detect success reaching the goal and progress to next level
 - [X] Detect defeat by discouragement
 - [X] add foods and bloat indicator
 - [X] scale hero waist related to bloat level
 - [X] create more levels
 - [ ] slow down if hungry or had too much to eat
 - [ ] add more text to explain things
 - [ ] add text bubbles with unhelpful comments
 - [ ] dig potholes
 - [ ] make others steal keys
 - [X] some level celebration/animation
 
* Installation and Development

** Download from itch.io

Download the latest version from [[https://snamellit.itch.io/bloatrunner][Bloatrunner page on Itch.io]].

Untar the filename, enter the newly created folder and launch `bloatrunner/bloatrunner`.

#+BEGIN_SRC
  tar -xzvf <download tar ball>
  cd <terrible name>
  bloatrunner/bloatrunner
#+END_SRC


*** DONE make an upload script which cleans up the filename

The current filename contains the GUIX UUID which is ugly and not very
userfriendly.

There should be some CI script to build/create the tarball, rename it
and upload it with a friendly name + version number.

No idea how to get the name of the tarball from guix pack without
parsing the output.

** Using Guix

We *highly recommend* using [Guix](https://guix.gnu.org/) to manage your
development environment.  Once Guix is installed, getting all of the
dependencies you need to develop is *easy*.  Just run `guix shell` from
the root directory of this repository and you'll be good to go!

In a hosted guix you can ensure you are in your profile by setting the 
environment in a `.envrc` file

```
export GUIX_PROFILE="/home/pti/.config/guix/current"
source "$GUIX_PROFILE/etc/profile"
export GUIX_LOCPATH="$HOME/.guix-profile/lib/locale"
use guix -l guix.scm

```

** Building from source

```
Assuming Guile and Chickadee are installed on your system, a fresh
project can be built like so:

./boostrap.sh
./configure
make -j$(nproc)
```

After the build system is initialized, only `make` needs to be run to
recompile the Scheme modules.

Note: On hosted guix the configure script might find the host guile
version instead of the guix provided one. This can lead to
incompatible bytecode errors.  To force to use a consistent guile use

```
./configure GUILE=$(which guile)
```

to ensure the right version is configured.

** Running the game

To run the game from the source checkout, use the `pre-inst-env`
wrapper script:

```
./pre-inst-env bloatrunner
```

** REPL-driven development

After the game is launched, a Guile REPL server will be running on
port 37146.  We recommend using the
[Geiser](https://geiser.nongnu.org/) Emacs extension for connecting to
it using `M-x connect-to-guile`.  Once Geiser connects to the REPL,
the game can be modified while it runs!

When the environment is set as indicated above and the emacs direnv
module is enabled, we can run `geiser-guile` as usual and everything
should work as expected.

To restart the game on crash I use *watchexec* to observe the folder and
restart on crash when the code is updated. That avoids scrolling
errors so I can read the error and immediately see if it is fixed on
saving.

```
$ watchexec -e .scm ./pre-inst-env bloatrunner
```


** DONE Bundling

Use `guix pack`.

For this we need a proper package definition in a module with the
build instructions and sources and outputs.

I followed the instructions at [[https://guix.gnu.org/en/blog/2023/from-development-environments-to-continuous-integrationthe-ultimate-guide-to-software-development-with-guix/][Ultimate Guide to Software Development
with Guix]] .

To add the assets we need to define them

#+BEGIN_SRC
asset_files = \
  assets/images/simples_pimples.png \
  assets/images/lr_penguin2.png \
  assets/images/glamshot.png \
  assets/levels/level1.tmx \
  assets/levels/tiles.tsx \
  assets/levels/level-001.map

nobase_dist_pkgdata_DATA = $(asset_files)

...
EXTRA_DIST = 					\
  $(SOURCES)				\
  $(subdir_files)
  README.org

#+END_SRC


see [[https://www.gnu.org/software/automake/manual/html_node/Data.html#Data][Architecture independent datafiles section of the automake manual.]]


#+BEGIN_SRC shell
guix pack -L .guix/modules bloatrunner
#+END_SRC

Generates a 750Mb  installed folder structure with everything in it, theoretically

To add the startup script :

#+BEGIN_SRC 

#+END_SRC

This startup script needs to be wrapped during installation to find
the libraries. This requires calling the `wrap-program` utility with
the environment variables set according to the installed environment.

#+BEGIN_SRC scheme
  (arguments
    '(#:modules ((guix build gnu-build-system)
                 (guix build utils)
                 (ice-9 popen)
                 (ice-9 rdelim))
      #:make-flags '("GUILE_AUTO_COMPILE=0")
      
      #:phases
      (modify-phases %standard-phases
                     (add-after 'install-bin 'wrap-program
                                (lambda* (#:key inputs outputs #:allow-other-keys)
                                  ;; (use-modules (guix build guile-build-system))
                                  ;; Wrap the 'gitile' command to refer to the right modules.
                                  (let* ((out    (assoc-ref outputs "out"))
                                         (chickadee (assoc-ref inputs "guile-chickadee"))
                                         (deps   (list out chickadee))
                                         (guile  (assoc-ref inputs "guile"))
                                         (effective (read-line
                                                     (open-pipe* OPEN_READ
                                                                 (string-append guile "/bin/guile")
                                                                 "-c" "(display (effective-version))")))
                                         (mods   (string-drop-right  ;drop trailing colon
                                                  (string-join deps
                                                               (string-append "/share/guile/site/"
                                                                              effective ":")
                                                               'suffix)
                                                  1))
                                         (objs   (string-drop-right
                                                  (string-join deps
                                                               (string-append "/lib/guile/" effective
                                                                              "/site-ccache:")
                                                               'suffix)
                                                  1)))
                                    (wrap-program (string-append out "/bin/bloatrunner")
                                                  `("GUILE_LOAD_PATH" ":" prefix (,mods))
                                                  `("GUILE_LOAD_COMPILED_PATH" ":" prefix (,objs)))))))
      ))

#+END_SRC

most of this is dynamically construct the content of the paths.

** Publishing to Itch.io

The autoconf also creates a `publish` script to create a distribution
and upload to itch.io.


* Asset Dependencies

** Hero sprites

[[https://opengameart.org/content/penguin-for-loderunner][Penguin for Loderunner from OpenGameArt]]

license: public domain CC0

** Tile Texture

[[https://opengameart.org/content/simple-broad-purpose-tileset][Simple Broad Purpose Tile Set]]

license: public domain CC0

** Box Art and similar images

These images were created with ChatGPT based  on my prompts. AFAICT
that makes me the owner of those things.

license: public domain CC0