Platz - A Uzebox platformer toolset

Topics on software tools like TileStudio, comments on documentation and tutorials (or the lack of) should go here.
Post Reply
User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Platz - A Uzebox platformer toolset

Post by paul » Tue Aug 04, 2009 9:29 pm

Platz is a platformer toolset for video mode 3. It handles most of the tedious tasks common to side-scrollers and allows you to focus on your game logic.

More specifically, Platz will manage:
- Loading and displaying level data
- Player/level collision detection
- Moving platforms
- Animated backgrounds
- Patterned backgrounds
- Event notification

Platz levels are stored as fill instructions and have on average roughly one tenth of the flash footprint of traditional maps. This affords huge levels with the potential for up to 255 unique screens of level data (any of which may be repeated multiple times for no extra flash). This number could go up dramatically if the '1284 ever comes to be.

Image

Collision detection is not simply go or stop; Platz will only restrict movement in the direction that is blocked and will detect collisions and handle movement across level slice seams (32 tile boundaries).

Animated backgrounds can range from npcs that you do not wish to waste sprites on, to any kind of environmental animation that you can think of. Loading, animating and displaying these special backgrounds is handled by Platz.

Image

Patterned backgrounds allow you to have interesting looking backgrounds (i.e. not all the same tile) without sacrificing the efficiency of fill instructions. A patterned bg will typically only cost a few more bytes than a regular background, and this cost is only paid once for any particular pattern, no matter the number of bgs that use it. Both patterned and animated bgs will automatically repeat to fill their containing region.

Image

Moving platforms act as expected and can move along either axis and be of any size.

Image

Platz triggers will fire an event whenever the player comes into contact with a bg that is flagged for this purpose. You can then respond to this in an appropriate manner. The demo uses triggers for water entry/exit form switches and for positional sound around the waterfalls. Simple AI guidance or checkpoints would also be possible.

Triggers can be setup to fire in different orientations so that the direction of the player's movement can be responded to appropriately. For example, the waterfall sfx will ramp up and fade away no matter the direction from which you approach.

Image

Platz's ram footprint is relatively low as resources are loaded only when required; its flash footprint is reasonable; and there are plenty of cycles left for typical game logic.

Using Platz for your game is very simple. The basic process is:

1. Initialise Platz table pointers
2. Initialise Platz core
3. Move to your starting screen/slice
4. If the player is moving, call PlatzMove
5. If you need to adjust the player's sprite dimensions, call PlatzSetBoundingBoxDimensions
6. Call PlatzTick each frame
7. Goto 4

The demo also shows how you can save/load your progress.

NB: You must have a formatted eeprom for the save/load feature to work. It may have other saved games, but it should be formatted in unused slots. Pac-Man does not format fully. You can rebuild with
DEMO_OPTIONS = -DFORMAT_EEPROM=1 in the makefile to force a full format. If using v1.09 of the emulator, you can simply delete any eeprom.hex file from the working directory.

Please see the makefile for options such as viewport slack, which dictates at what point the camera will begin following the player. Also note that Platz is still in its early stages and may change significantly in future releases. A version for video mode 2 will hopefully allow for dual-axis scrolling while retaining all of the current features.

TODO list:
- Projectile collisions
- NPC collisions (cycles permitting)
- Trigger system expansion
- Optimization review

I'm happy for feedback or feature requests/submissions for the TODO list. I'll update this post in the coming days with a link to a wiki guide on Platz usage.

Controls:

A: Toggle Lynx/Dragonfly form
Start: Save state
Select: Load state
Dpad to move (up is jump in Lynx form)
Turtle form transition is done with triggers.
Attachments
platz_alpha_0.3.1.zip
Fixed bug in waterfall code to ramp up/down more smoothly
(253.21 KiB) Downloaded 244 times
Last edited by paul on Sat Aug 08, 2009 11:57 am, edited 1 time in total.

braddock
Posts: 26
Joined: Fri Jul 31, 2009 12:09 pm

Re: Platz - A Uzebox platformer toolset

Post by braddock » Wed Aug 05, 2009 6:27 am

Wow. Impressive.

Would your system be at all useful (if under-utilized) for 2D text scrolling with dynamic loading of text? Say, for a book reader or long article? Or would it be easier just to code that from scratch?

User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Re: Platz - A Uzebox platformer toolset

Post by paul » Wed Aug 05, 2009 1:21 pm

braddock wrote:
Would your system be at all useful (if under-utilized) for 2D text scrolling with dynamic loading of text? Say, for a book reader or long article? Or would it be easier just to code that from scratch?
I don't think Platz would perform well in that circumstance. Space savings are gained through repeated adjacent patterns that would be far less prevalent in readable text. It is possible to make a Platz level that takes up more flash than an equivalent map, but it would not be a level that is ever likely to be created, given typical platformer aesthetics. I think text would lean towards this end of the spectrum. There may be some base code that could be modified and used for that purpose.

If it's a picture book (my kinda book ;)), then Platz could certainly play a role.

User avatar
JRoatch
Posts: 108
Joined: Mon May 11, 2009 11:48 pm
Contact:

Re: Platz - A Uzebox platformer toolset

Post by JRoatch » Thu Aug 06, 2009 10:58 pm

Very well done paul. I'm not sure how it works internally, but it reminds me of how the levels in some NES games(Metroid, Super Mario Bros) are constructed.

Are the Moving platforms part of the background, or are they a big sprite?

User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Re: Platz - A Uzebox platformer toolset

Post by paul » Fri Aug 07, 2009 3:40 am

JRoatch wrote:
Are the Moving platforms part of the background, or are they a big sprite?
They're background tiles offset at one-pixel intervals over the space of a single tile transition (but need to be done in both directions for each axis). I will try to allow for a sprite-based moving platform option for vmode 2.

I'm in the process of documenting the toolset on the wiki, and should be done today or tomorrow. Hopefully that will make it more approachable.

User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Re: Platz - A Uzebox platformer toolset

Post by paul » Fri Aug 07, 2009 10:40 pm

Full documentation for the Platz toolset can now be found on the Uzebox wiki at:

http://uzebox.org/wiki/index.php?title=Platz_Toolset

Or by following the link under the Tools section of the wiki's main page. If anyone decides to utilize Platz for a project and is having trouble understanding any of the concepts, please feel free to ask as many questions as you need in this thread. It's sometimes difficult to document well without any feedback, but I think it is at least relatively clear.

User avatar
uze6666
Site Admin
Posts: 4487
Joined: Tue Aug 12, 2008 9:13 pm
Location: Montreal, Canada
Contact:

Re: Platz - A Uzebox platformer toolset

Post by uze6666 » Sat Aug 08, 2009 1:13 am

Paul, awesome work as usual! Very detailed docs you have written there, it's much clearer to see what can be achieved and how to do it. I'm thinking about a remake of the original Super Mario bros. to see how to use it...

-Uze

User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Re: Platz - A Uzebox platformer toolset

Post by paul » Sat Aug 08, 2009 12:00 pm

uze6666 wrote:I'm thinking about a remake of the original Super Mario bros. to see how to use it...

-Uze
That'd be really cool. If you find time, I'd love to play it.

I've uploaded a newer version that fixes a small bug in the waterfall sfx (making it smoother). The latest code can always be found by following the svn link from the wiki.

User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Re: Platz - A Uzebox platformer toolset

Post by paul » Tue Dec 29, 2009 2:08 am

Platz v1.0 is now available. The most notable inclusion is that of Mutable Bgs. Mutable Bgs are dynamic in their presentation and collision status. They may also contain a custom payload which can be used in almost any way you like.

An example of this is in B.C. Dash where three mutable Bgs combine to create an effect. The first is the bomb which... explodes as bombs tend to. The bomb clears the area contained by the bomb target bg which in turn switches on the hidden animation so that water now animates where land once was. None of this behavior is defined by Platz - you can use the mutable payload as you wish. A bitmap in RAM (very small footprint or maybe 8 bytes) is used to maintain mutable state in B.C. Dash. You can maintain more state to do more interesting things, but that will come with time. State can be saved to eeprom and so persistent destruction is possible (persistent destruction sounds fun, doesn't it :twisted: ).

Another added feature is the BGQ flag. This flag will allow you to query collisions for bgs and choose to obey or ignore them. In the past Platz has typically deferred this type of flexibility to client logic and so this trend continues. Callback overhead is minimal as client logic is usually simple and the call is only made when a collision is imminent (i.e not very often and only ever to a couple of bgs at most at any one time).

There are also a couple of bug fixes and numerous optimizations. The changelog is reprinted here:

Code: Select all

Platz 1.0.0
- Demo game created with LePlatz v1.0 available:
	http://code.google.com/p/uzebox-paul/downloads/list
- Eliminated compiler warnings of unused variables when setting MAX_MOVING_PLATFORMS=0 or MAX_ANIMATED_BGS=0.
- Fixed buffer overflow when using more than the default number of moving platforms per slice.
- Fixed painting of initial frame for slices with bg animations that exist in multiple Outer bgs.
- SLOW_BG_PATTERNS now incurs only a very slight cycle and flash penalty.
- BG flags BGTH and BGTV have been merged into BGT. BGTV's bit flag has been reassigned.
- Patterned BGs (BGP) are now stored as traditional maps. This makes large patterns far more manageable
  from a development standpoint.
- Platforms can now move in steps. This reduces required tiles from 44 to 1. Movement precision is
  tile-based for stepped moving platforms. These are best used for horizontal movement or when
  the player will not be carried by the platform.
- Platforms now specify their clear tile individually. This allows for placement of platforms
  against different single-tile backgrounds within a single game. Note that a full set of tiles
  are required for each background if smooth platforms are utilised.
- Platform clear tiles should be in the first 64 tiles (i.e masked with 0x3F).
- BGM flag indicates a mutable BG. These BGs can be dynamically customized and generate events
  upon player interaction. Customizations may persist for the current session or be saved to
  EEPROM and persist indefinitely (say for a saved game). BGs can be changed visually and collision-wise,
  such that deformable BGs are possible (NB: the deformed BG must be a valid BG and cannot be split
  into multiple BGs).
- BG animations (BGA) no longer have a positional requirement in their Inner/Outer BG index - instead,
  they have a separate directory aswell as entries in the main BG directory.
- Synch attribute added to BG animations. Setting to non-zero ensures animations of a similar type
  are synchronized accross slice boundaries.
- Programs suffering compatibility issues with Platz 1.0.0 can find Platz 0.3.2 at:
	http://code.google.com/p/uzebox-paul/source/browse/#svn/trunk/tools/platz-0.31
  Alternatively, queries regarding steps to make your pre-1.0 program 1.0 compatible can be posted
  to the official Uzebox forums: http://uzebox.org/forums/viewtopic.php?f=6&t=527
- PlatzMapSprite now takes an extra argument for sprite flipping
- Objects now index into the same maps table used by Patterned Inner Bgs. The object data structure is
  25% smaller due to not having to store the map's address internally.

Platz v1.1 will see both sprite and tile-based projectiles (because I need them for Gradiuze). Code is available here.

If you are making a game based on 0.31 and wish to know what changes are required to convert to the 1.0 codebase, feel free to ask any questions in this thread. I will update the Platz wiki page in the new year.

User avatar
paul
Posts: 457
Joined: Sat May 02, 2009 8:41 am
Location: Brisbane, Australia

Re: Platz - A Uzebox platformer toolset

Post by paul » Wed Feb 03, 2010 2:34 am

Just a quick update on Platz v1.1.

The new version is over 2k lighter when compiled with the B.C. Dash demo. This is primarily due to Mutable Classes, a PLATZ_SLIM option and revamped collision detection code.

Mutable classes are a cheap form of Mutable BG. They cost the same as a regular Inner BG in the amortized sense. Mutable classes are likely to be more commonly used than Mutable Bgs. Situations where the reaction to events generated by the BG, and the presentation of the BG are common, lend themselves to utilizing Mutable classes. An example would be the rings that Sonic collects - they are always the same dimensions; always have the same animation; and always add one to your count. Mutable Classes do not come in pairs like Mutable BGs; instead, they reference a shared table for their payload.

PLATZ_SLIM is on by default but can be set to 0 in the makefile. You will notice its visual penalty when using PlatzMoveToSlice - the painting cascades across the screen (briefly) rather than being painted all at once. A minor side-effect for a large 1k saving.

Documentation is updated to match the new version. I should note that there were a couple of minor function interface changes that aren't compatible with previous code - I didn't recall these until writing the documentation, but they're so minor that I don't think it's much of an issue to update any existing code. If you're using LePlatz, changes will be fairly transparent.

Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest