Forums

Sega Master System / Mark III / Game Gear
SG-1000 / SC-3000 / SF-7000 / OMV
Home - Forums - Games - Scans - Maps - Cheats - Credits
Music - Videos - Development - Hacks - Translations - Homebrew

View topic - New Master System Z80 Library

Reply to topic
Author Message
  • Joined: 17 Jun 2017
  • Posts: 19
Reply with quote
New Master System Z80 Library
Post Posted: Wed Apr 21, 2021 8:18 pm
Hi all,

I've been working on a Master System wla-dx Z80 library and have uploaded it to: https://github.com/lajohnston/smslib

The lib handles various aspects of the Master System hardware, such as palettes, patterns, sprites and tilemap. It's not a full engine or framework as such but does take care of a lot of the lower-level stuff and boilerplate required to spin up projects. It essentially takes all I've learned from this website and codifies it into macros.

If anything the /examples and /docs should provide beginners with some good reading material. The examples are ordered in a way I hope provides a fairly gentle learning curve, starting with the Hello World tutorial based on Maxim's famous one, then progressing to more complex aspects such as sprites, VBlank timing and paging. The examples double as tests for the library and also help me identify pain points in the API.

More information is in the readme and docs. The current version handles the basics but as time goes on and I use it for projects I expect to iron out annoyances that pop up, add missing features and generally tighten the routines. I haven't added PSG or advanced tilemap/scrolling support as I think these aspects are better handled by dedicated libs such as PSGLib and GSLib, but I may at some point include basic support for example purposes.

I'm not sure what feature to add next so looking for ideas and suggestions!

eljay
  View user's profile Send private message
  • Joined: 29 Mar 2012
  • Posts: 879
  • Location: Spain
Reply with quote
Post Posted: Thu Apr 22, 2021 7:27 am
Always happy to see new libraries appear for our beloved console! Starred!
  View user's profile Send private message
  • Joined: 23 Aug 2009
  • Posts: 213
  • Location: Seattle, WA
Reply with quote
Post Posted: Thu Apr 22, 2021 8:24 pm
Very cool! I'm really interested in how you're using some of the macros, and I didn't realize you could do dot notation for defines. I'll borrow those ideas for my own lib :)
  View user's profile Send private message
  • Site Admin
  • Joined: 19 Oct 1999
  • Posts: 14688
  • Location: London
Reply with quote
Post Posted: Thu Apr 22, 2021 9:59 pm
WLA DX seems to accept almost any text in most places, with the unfortunate exception of labels. So you can name your macros with emoji if you like, for example.
  View user's profile Send private message Visit poster's website
  • Joined: 01 Feb 2014
  • Posts: 849
Reply with quote
Post Posted: Fri Apr 23, 2021 6:18 am
This looks really solid. Great work. If I hadn't made my own variants of most of these bits and pieces already, I'd start using your lib right away. Hopefully, it will be another step in lowering the entry threshold for new developers who want to try their hand on some assembler code for our favourite machine.
  View user's profile Send private message
  • Joined: 17 Jun 2017
  • Posts: 19
Reply with quote
Scrolling
Post Posted: Sun Apr 30, 2023 9:47 am
Just a note that I did end up implementing tilemap scrolling for this library in the end. It took longer to implement than I care to admit, and it still isn't quite as fast as GSLib!

The aim of this lib is to be a low-level API, with some optional sprinkles on top bundled in to reduce boilerplate and speed up development. The way I've implemented it for this goal is to split up the task as follows:

tilemap.asm (docs) - handles the hardware aspects (scroll registers, col/row scroll detection and VRAM col/row write addresses)
optional scroll handlers - build on tilemap.asm to implement higher-level logic such as metatiles

I've included a couple of scroll handlers, one for raw tiles (docs, example) and one for metatiles (docs, example). The raw one was included more as an example and as a stepping stone for me to develop the tilemap.asm API. Compared to GSLib, the current metatile handler does have a couple of features that might be useful though, including:
- Variable metatile sizes (at assemble-time). Each dimension can be 2, 4, 8 or 16 (i.e. 2x2, 2x4, 8x4 etc)
- It doesn't use shadow registers (perhaps useful in some cases)
- Optional bounds detection

The metatile definition data just consists of raw tiles, for speed. The metatilemap format uses pre-rotated reference values to these as in GSLib, to speed up the lookup. The map width and height is variable at runtime to allow levels of varying sizes.

With 4x4 and larger metatiles it's about on speed parity with GSLib's 2x2 metatiles. For some reason the CPU usage is about the same for all sizes but suddenly spikes a little with 2x2 metatiles, so that's a fix/optimisation I'll look into at some point. I'm putting this aside for now though to work on other aspects but I intend to come back to it later :)
  View user's profile Send private message
  • Joined: 05 Sep 2013
  • Posts: 3763
  • Location: Stockholm, Sweden
Reply with quote
Post Posted: Tue May 02, 2023 9:29 am
Good to see this happening, and also to hopefully have a good alternative to GSLib which is, unfortunately, now abandoned.
  View user's profile Send private message Visit poster's website
  • Joined: 25 Mar 2019
  • Posts: 20
  • Location: Nagoya, Japan
Reply with quote
I would like to use the library too
Post Posted: Wed May 10, 2023 4:01 am
I am a beginner in programming and am currently learning assembly.
I would very much appreciate the library.
However, I do not know how to use this library.
  View user's profile Send private message
  • Joined: 17 Jun 2017
  • Posts: 19
Reply with quote
Post Posted: Wed May 10, 2023 9:13 pm
Hi hogel :)

If you're completely new to assembly programming then I'd highly recommend you start with Maxim's Hello World tutorial if you haven't seen it already:

https://www.smspower.org/maxim/HowToProgram/Lesson1AllOnOnePage

That will familiarise you with wla-dx and the basic concepts of Master System programming. After that, you can look through the SMSLib examples here:

https://github.com/lajohnston/smslib/tree/main/examples

The first helloWorld example implements Maxim's tutorial but using SMSLib. The examples are ordered and introduce more complex concepts such as VBlank timing, sprites and scrolling tilemaps. The docs also contain useful information about various concepts.
  View user's profile Send private message
  • Joined: 25 Mar 2019
  • Posts: 20
  • Location: Nagoya, Japan
Reply with quote
Post Posted: Thu May 11, 2023 3:41 am
Thank you eljay for your reply.
Thank you for teaching me.
I will read and study the doc in the link.
eljay wrote


https://github.com/lajohnston/smslib/tree/main/examples

The first helloWorld example implements Maxim's tutorial but using SMSLib. The examples are ordered and introduce more complex concepts such as VBlank timing, sprites and scrolling tilemaps. The docs also contain useful information about various concepts.
  View user's profile Send private message
  • Joined: 06 Mar 2022
  • Posts: 598
  • Location: London, UK
Reply with quote
Post Posted: Thu May 11, 2023 8:41 am
Hey @eljay, great stuff!

I was looking at your lib maybe a year ago and thought it looked really promising but I see you've done a load of work on it since, very impressive indeed.

I think I'll try building my next game with this to give it a proper test drive.

A couple of observations though:

1. I get the philosophy of speed first, but last time I tried using the lib I felt like I hit a very immediate developer experience wall having to keep checking what registers were clobbered and then manually pushing and popping registers. I wonder if there's an option where you could add a set of alternative "safe" wrappers for all the routines which save registers and allows for much quicker prototyping? Then when people need to optimise it's just a case of switching to use the original "fast" routines.
2. Although you chose the name ages ago, I do think it's a shame it's called smslib which is also the name of sverx's C library. Just because it makes referring to the two libraries a bit confusing. I wonder if there's any room either way to tweaks the names and allow better differentiation?

I've also whipped up a quick github project template based on one I put together for someone else here on the forums a while back:

https://github.com/retcon85/template-sms-wladx-lite-eljaysmslib

The idea is that you can create a new project in github based from this template, pull the submodule for the lib and it should pretty much build out of the box (straight into your helloworld example).

Finally @hogel and anyone else who's reading and just starting out, I would highly recommend trying my Docker toolchain as I think it's probably the quickest start possible for a hello world, especially if you already have Docker installed, although the image is still a work in progress.

https://hub.docker.com/r/retcon85/toolchain-sms

It means you don't need to faff around manually installing all the tools on your machine and it comes with WLA-DX and DevkitSMS.

I'm told it works on Windows and I use it all the time on MacOS / Linux. I keep meaning to write a full forum post explaining and will one of these days!
  View user's profile Send private message Visit poster's website
  • Joined: 17 Jun 2017
  • Posts: 19
Reply with quote
Post Posted: Thu May 11, 2023 10:03 pm
Thanks, that template's a great idea :) I was wondering what a good mechanism there would be that wouldn't involve copy and pasting one of the examples and changing it around.

Quote
I think I'll try building my next game with this to give it a proper test drive.

That's the stage I'm at with it at the moment. It's working well so far and it makes it very quick to get from nothing to a working ROM displaying graphics. I've been learning and building specific examples with it but I won't really appreciate what's missing and what the pain points are until I've built a full project or two with it. I shall fix these problems as I go along. It's still a pre-release at this stage and the API has some maturing and settling to do but I'll try to keep breaking changes documented in the version releases.

Quote
I do think it's a shame it's called smslib which is also the name of sverx's C library. Just because it makes referring to the two libraries a bit confusing. I wonder if there's any room either way to tweaks the names and allow better differentiation?

Yes, the current name was a working title I made before I was aware of the existing one, but hopefully a more distinguishing name comes to mind before the 1.0 release :)

Quote
last time I tried using the lib I felt like I hit a very immediate developer experience wall having to keep checking what registers were clobbered and then manually pushing and popping registers. I wonder if there's an option where you could add a set of alternative "safe" wrappers for all the routines which save registers and allows for much quicker prototyping? Then when people need to optimise it's just a case of switching to use the original "fast" routines.

It's admittedly the most controversial aspect of it and involves a mindset shift. In theory you shouldn't need to know what gets clobbered and just assume it will, as if it doesn't clobber a register now a future update might! It's caught me out a couple of times but it's not actually caused me too many problems. A lot of the library's routines perform a given standalone task like `sprites.copyToVram`, then you move onto doing something completely different, so in these cases you don't need any register state to have been preserved. When it is needed I find a lot of the time it's possible to re-order my code to place the library call earlier, before loads etc., without needing to actually push/pop anything. I have though been mulling a safe approach as a middleground, either safe wrappers or a global setting you can enable/disable at various points
  View user's profile Send private message
  • Joined: 25 Mar 2019
  • Posts: 20
  • Location: Nagoya, Japan
Reply with quote
Post Posted: Tue May 16, 2023 4:26 am
willbritton wrote
Finally @hogel and anyone else who's reading and just starting out, I would highly recommend trying my Docker toolchain as I think it's probably the quickest start possible for a hello world, especially if you already have Docker installed, although the image is still a work in progress.

https://hub.docker.com/r/retcon85/toolchain-sms

It means you don't need to faff around manually installing all the tools on your machine and it comes with WLA-DX and DevkitSMS.

I'm told it works on Windows and I use it all the time on MacOS / Linux. I keep meaning to write a full forum post explaining and will one of these days!


Thank you! @willbritton.
I am using wla-dx, following the Maxium tutorial.
I need to understand C language to use DevkitSMS. But I don't understand C language, so unfortunately I can't use it.
Now I am learning more about horizontal scrolling of the map than the screen size.
I read forums and demo programs, but I am having a hard time understanding it.

Sorry if my writing is strange. I am deepL translating because I don't understand English very well.
  View user's profile Send private message
Reply to topic



Back to the top of this page

Back to SMS Power!