Apple II+ clone of Amidar
Go to file
2021-05-04 09:52:51 -07:00
kfest2018 Removed unused HGR2 page 2018-07-21 21:19:52 -07:00
actors.s Added comments; changed zero page so it will mostly work on the atari 2017-08-01 19:27:54 -07:00
apple-sprite9x11.png Copied demo program from quicksprite as initial code 2017-07-17 10:56:20 -07:00
atari-sprite9x11.png Added black border around fuji sprite 2017-07-21 21:03:26 -07:00
background.s Added debug check for boundary crossing in text screen or tile movement 2017-08-02 12:27:41 -07:00
constants.s Added ACTOR_FLAG to set high bit on text page at enemy location 2018-07-20 18:31:56 -07:00
debug.s Added debug check for boundary crossing in text screen or tile movement 2017-08-02 12:27:41 -07:00
fatfont128.dat Added lives remaining display; reduced score display to 5 digits & lowered scoring values to more like a 1980 game 2017-07-22 08:46:09 -07:00
fujirun-v1.dsk Added ACTOR_FLAG to set high bit on text page at enemy location 2018-07-20 18:31:56 -07:00
gen_random_seeds.py Added uniqueness check to rnd number seed generator 2017-08-29 09:03:02 -07:00
kansasfest-hackfest.hgr Updated kansasfest image 2017-08-17 13:44:12 -07:00
kansasfest-hackfest.png Updated kansasfest image 2017-08-17 13:44:12 -07:00
LICENSE Changed to the MPL 2021-05-04 09:52:51 -07:00
logic.s Added ACTOR_FLAG to set high bit on text page at enemy location 2018-07-20 18:31:56 -07:00
lz4.s Added Peter Ferrie's lz4 decompressor to hold title screen so it can be reused 2017-07-28 06:13:58 -07:00
macros.s Maze generation working 2017-07-19 17:11:09 -07:00
main.s Added ACTOR_FLAG to set high bit on text page at enemy location 2018-07-20 18:31:56 -07:00
Makefile Fixed name of asmgen-generated products 2018-07-20 08:47:19 -07:00
maze.s Moved screen functions to platform-apple2 2017-07-25 15:51:25 -07:00
mazegen.py Fixed sub-tile movement for player 2017-07-22 12:05:22 -07:00
mazetiles.s Maze generation working 2017-07-19 17:11:09 -07:00
platform-apple2.s Added ACTOR_FLAG to set high bit on text page at enemy location 2018-07-20 18:31:56 -07:00
player-missile-2.hgr Added pre-generated HGR screens so you don't need tohgr unless rebuilding images 2017-08-17 10:12:39 -07:00
player-missile-2.png Replaced the partycrasher logo with player/missile. Don't want to tempt the ire of the shambling zombified remains of Atari 2017-07-26 11:16:06 -07:00
player-missile.hgr Added pre-generated HGR screens so you don't need tohgr unless rebuilding images 2017-08-17 10:12:39 -07:00
player-missile.png Replaced the partycrasher logo with player/missile. Don't want to tempt the ire of the shambling zombified remains of Atari 2017-07-26 11:16:06 -07:00
rand.s Moved debug random test to debug.s 2017-07-25 16:30:48 -07:00
README.rst Added images to README 2017-08-17 19:57:58 -07:00
run.sh Added run script for mazegen 2017-07-17 11:14:37 -07:00
title.hgr Changed title page font for name; don't switch back to tohgr at line 167 when generating HGR screen 2017-08-17 17:59:31 -07:00
title.png Changed title page font for name; don't switch back to tohgr at line 167 when generating HGR screen 2017-08-17 17:59:31 -07:00
title.xcf Changed title page font for name; don't switch back to tohgr at line 167 when generating HGR screen 2017-08-17 17:59:31 -07:00
vars.s Clear $800 for variable storage & reordered vars so X stuff and Y stuff is grouped together 2017-08-02 11:36:24 -07:00
wipes-demo.s Increased delay after scrolling FujiRun title screen into view 2017-08-17 10:05:15 -07:00
wipes-null.s Added scrolling wipe for thanks screen 2017-07-25 17:57:16 -07:00

========
Fujirun
========

My (winning!) entry in the `KansasFest <https://www.kansasfest.org/>`_ 2017 `HackFest <https://www.kansasfest.org/hackfest/>`_ competition.

.. image:: https://playermissile.com/_images/fujirun_title_card3.png
   :align: center

.. image:: https://playermissile.com/_images/fujirun_title_screen.png
   :align: center

.. image:: https://playermissile.com/_images/fujirun_gameplay.png
   :align: center

Running
=======

Fujirun is written for an Apple ][+ with 48K of memory.

A pre-built disk image is included, so no need to reassemble the code unless
you are changing something. Use your favorite Apple II emulator to boot the disk image ``fujirun-v1.dsk``.


Building
========

To build from the assembly source, you will need the following programs:

* `Python 2.7 <https://www.python.org/downloads/>`_
* `ATasm <http://atari.miribilist.com/atasm/>`_, which, while ostensibly an *Atari* macro assembler, produces generic 6502 code and can be used on any 6502 machine
* `lz4 <https://lz4.github.io/lz4/>`_, a compression program suitable for fast decompression on the 6502

For Python, you will need these additional packages:

* `atrcopy <https://github.com/robmcmullen/atrcopy>`_, my disk image utility
* `asmgen <https://github.com/robmcmullen/asmgen>`_, my 6502 code generation utility

which are available through pip. Once Python is installed, use: ``pip install atrcopy asmgen``.


Gameplay
========

This is a clone of the arcade game Amidar. You control an apple, trying to fill
in rectangles while avoiding the booataris. Moving on the lines of the maze,
you change the color from white to green the first time you walk on a segment
of a line. When all segments surrounding a rectangle are green, the rectangles
will be filled.

* 1 point is awarded for each segment of a line
* 20 points per segment height are awarded for each box filled, so for example
  40 points for a box that is two segments high, 60 for 3 segments high, etc.

There are two types of booataris: an orbiter than continually makes
counterclockwise circuits around the outside of the maze, and amidars which
follow the rules of "ghost legs". Amidars start on the top of the maze and move
downward. When the reach a horizontal branch, they **must** take it. Once they
reach the end of a branch, they will resume their downward direction. When they
reach the bottom, they will move left or right to a different vertical line and
begin travelling upwards, again following the same rule that when they hit a
horizontal line, they **must** take it.

While moving up and down, the amidars behave deterministically: there is no
randomness at all. The only random bit of their movement is choosing which line
to start down (or up) when reaching the top (or bottom).


Game Status
===========

As coded for the HackFest, the game has a single screen and is a single player
game. At this point, nothing happens when completing the maze. I ran out of time during KansasFest.

I am planning on adding:

* actually moving on to the next level when you complete a level
* some sort of effect when the player gets caught by a booatari.
* multiple levels
* sound
* two player simultaneous play
* an Atari 8-bit port

Bugs
----

By design, the "pac-man" bug is present so the player and an amidar can pass
through each other if they happen to exchange grid squares in a single turn. In
practice this happens more often than I thought it would, so I'll have to
readdress this.

After you lose all your lives and restart (by pressing any key), the amidars
will work correctly until they get to the bottom, after which one will continue
going down after the bottom row and stomp all over memory and crash. I still
haven't been able to debug this.


Code Organization
=================

Source files
------------

* ``main.s`` - main driver
* ``platform-apple2.s`` - Apple II specific code
* ``wipes-demo.s`` - title screen animation
* ``wipes-null.s`` - stubs for title screen to make faster booting test image
* ``actors.s`` - player/amidar initialization
* ``background.s`` - printing, text screen utilities, screen damage
* ``constants.s`` - variables. Just kidding. Constants.
* ``debug.s`` - debugging utilities
* ``logic.s`` - player/amidar movement logic
* ``lz4.s`` - Peter Ferrie's `lz4 decompressor <http://pferrie.host22.com/misc/appleii.htm>`_
* ``macros.s`` - guess
* ``maze.s`` - maze generation code
* ``rand.s`` - random number generator and utilities
* ``vars.s`` - uninitialized variable declarations

Resource files
--------------

* ``apple-sprite9x11.png`` - your plucky hero
* ``atari-sprite9x11.png`` - did somebody say boo?
* ``fatfont128.dat`` - modification of Michael Pohoreski's font from his `HGR tutorial <https://github.com/Michaelangel007/apple2_hgr_font_tutorial>`_ to change a few text characters and add the maze tiles
* ``kansasfest-hackfest.png`` - source for 3rd title card
* ``kansasfest-hackfest.hgr`` - conversion to HGR binary data using tohgr and asmgen
* ``player-missile-2.png`` - source for 2nd title card
* ``player-missile-2.hgr`` - conversion to HGR binary data using asmgen
* ``player-missile.png`` - source for 1st title card
* ``player-missile.hgr`` - conversion to HGR binary data using asmgen
* ``title.xcf`` - GIMP source image for title screen (4th title card upon load)
* ``title.png`` - source for HGR conversion
* ``title.hgr`` - conversion to HGR binary data using tohgr and asmgen

Prototyping
-----------

* ``mazegen.py`` - python, curses based prototyping code for developing maze algorithm and enemy logic


Code Walkthrough
================


Notes
-----

* the graphics for the maze are tile-based, 7x8 tiles
* the maze is generated in text page 1 and copied to the HGR screens
* text page 1 is used as the reference for what should be drawn to or changed on the HGR screens
* page flipping is used
* the asmgen sprite compiler can be told to use damage, which reports back information about which bytes have changed when drawing the sprite
* the damage reported is actually text row/col so the fast font routine can copy the tiles over the damaged area
* players/amidars (actors) position is based the centers of each sprite, but location is tracked using the corresponding row/col in the text page and the pixel location within each tile
* any place you see the "_smc" extension, that's a target for self-modifying code. Got that from Quinn Dunki.


References
==========

* Quinn Dunki's `sprite compiler <https://github.com/blondie7575/HiSprite>`_ and `my modifications <https://github.com/robmcmullen/asmgen>`_
* Michael Pohoreski's `HGR Font Tutorial <https://github.com/Michaelangel007/apple2_hgr_font_tutorial>`_
* Peter Ferrie's original `one sector boot loader <https://github.com/peterferrie/standard-delivery>`_ and `my modifications <https://github.com/robmcmullen/standard-delivery>`_
* Peter Ferrie's `LZ4 unpacker <http://pferrie.host22.com/misc/appleii.htm>`_
* Sheldon Simms' `PNG to HGR converter <http://wsxyz.net/tohgr.html>`_