Lack of instructions in examples

[sasja-san]

I'm trying to work from 03-sprite-animation in https://github.com/dciabrin/ngdevkit-examples. I've been at this for a few days but I just don't get it.

Around line 125 this happens:

    static const u16 idle_frame[8] = {256, 272, 288, 304, 320, 336, 352, 368};
    static const u16 walk_frame[8] = {384, 400, 416, 432, 448, 464, 480, 496};

I'm trying to put my own graphics into a ROM I thought it would be a good starting off point to look at this particular example. But I just can't figure out where these numbers are coming from...

I understand that each frame of the gif source is 64x64 pixels, meaning 4x4 tiles.

Are these numbers emitted somewhere in C ROM creation chain and I just missed them? Or is this just a raw calculation that I should figure out from the wiki. I find that there are many magical numbers for this to be a good example.

[dogruis]

Yeah, I went down this exact hole a month ago — those numbers aren't emitted anywhere, they're hand-written cROM tile indices. Once you know the two things behind them they stop being magic and you can rederive every one yourself.

The 256 is just where your sprite lands in cROM, and that's the Makefile's doing, not any tool's. Check the cROM deps:

$(CROM1): $(BUILDDIR)/assets/base-crom-logo.c1 # logo goes in FIRST
$(CROM1): $(BUILDDIR)/assets/all.c1 # your sprite goes in SECOND
Tiles are numbered from 0 and the ngdevkit logo gets packed ahead of yours. The logo is exactly 256 tiles — you can check it: ls -l build/assets/base-crom-logo.c1 is 16384 bytes, and a 16×16 tile is 64 bytes in a cROM half, so 16384/64 = 256. So all.gif starts at tile 256. That's the whole story — 256 literally means "whatever got packed before me." Pull the logo line out of the Makefile and your sprite starts at 0.

The +16 is just the frame size. all.gif is 64×1024, which is 4 tiles wide by 64 tall = 256 tiles, and each frame is 64×64 = 4×4 = 16 tiles. So it's 16 frames stacked top to bottom, 8 idle then 8 walk, and frame N starts at 256 + N16. That's your idle = 256,272,…368 and walk = 384,…496 (384 is just 256 + 816, i.e. right after the idle frames).

The bit that actually messes with your head is the tile, tile+4, tile+8, tile+12 inside update_sprite — that's the Neo Geo vertical-strip thing. A hardware sprite is 1 tile wide and up to 32 tall, so a 4×4 character is really 4 sprites stood side by side (that's the i*64 loop over SCB1). tiletool numbers the strip left-to-right then top-to-bottom, so one frame is:

base+0 base+1 base+2 base+3 +1 = one tile right
base+4 base+5 base+6 base+7 +4 = one tile down
base+8 base+9 base+10 base+11
base+12 base+13 base+14 base+15
Each sprite is one column, so column i gets base+i, +4, +8, +12 walking down. right_tiles = {0,1,2,3} just picks the column; mirror flips it to {3,2,1,0} and sets the H-flip bit per tile.

So for your own art: lay it out as a 4-wide vertical strip gif, frames stacked top to bottom, 16 colours with index 0 = transparent (same shape as all.gif). Add it to cROM in the Makefile the same way ($(CROM1): build/assets/yours.c1 plus the .c2), and your start tile = however many tiles are packed before it — 256 if you keep the logo, 0 if you drop it. Then frame N = start + N*(tiles per frame), and tiles per frame = width × height in tiles, so 16 for a 4×4.

And honestly — you're not wrong, these look like magic numbers and I just see the examples as a showcase really. It's written to be short so it just hardcodes what a real project would generate. The usual fix is an asset pipeline that converts your gif and spits out a header (#define HERO_IDLE_0 256 …) so you never hand-count tiles again. That's the bit you're feeling the lack of.

[dogruis]

I might write a book about this in the future if I can pull this off after my project lands on NeoGeo AES+

[sasja-san]

I might write a book about this in the future if I can pull this off after my project lands on NeoGeo AES+

Haha, I was thinking the same thing 😜
If you want to team up for writing some articles for the wiki (or anywhere else), I'm up for it 👍

---

In this particular example a file called all.pal is created. What I think I might want instead is to get one file (or one printout) per asset, with C style comments. It should give me the source file name, the tile offset numbers in the file and a C style array with the palette.

So for the assets in example 03 I would get a block like this, with the comment in it:

// setup/prepare-hero/idle.gif, stored in C1 + C2
const u16 pal_prepare_hero_idle[16] = {
0x8000,0xf111,0x0223,0x3423,0x4633,0x4a33,0x1953,0x5d72,0x0da6,0x3878,0x79ab,0x5ec9,0xfcdf,0x8000,0x8000,0x8000
};
const u16 frm_prepare_hero_idle[8] = {256, 272, 288, 304, 320, 336, 352, 368};

// setup/prepare-hero/idle.gif, stored in C1 + C2
const u16 pal_prepare_hero_walk[16] = {
0x8000,0xf111,0x0223,0x3423,0x4633,0x4a33,0x1953,0x5d72,0x0da6,0x3878,0x79ab,0x5ec9,0xfcdf,0x8000,0x8000,0x8000
};
const u16 walk_walk[8] = {384, 400, 416, 432, 448, 464, 480, 496};

If you're keeping good tabs on your assets, or you have something like this (see here: #147), it shouldn't be too hard to lump the right things together in your code.

Does this make sense? That way I would could take that and paste it in the appropriate place in my code, next to where all the logic for this entity would exist. Maybe the two python scripts (paltool.py and tiletool.py) already do this?

[dogruis]

I wrote an entire toolkit in order to mash my assets together and generate a TextureIds.c and TextureIds.h same for sound and level with all that information. It would take me quite a while to make it more generic and available for other people. But that would aleviate the difficulty of working with magic numbers and then having to constantly changing these number manually which is error prone.

[dciabrin]

There's a middle ground to reach most likely.

I fully agree that the examples look like magic, I'll try to clear out the misunderstanding.

The real issue here is "as a programmer, how do i want to track my assets?"

• I think ngdevkit should not morph into a game engine, because for one the engines are always very opinionated or very generic. but on old hardware you can't afford being generic most of the time for performance reasons.
• I talked to a couple of folks about this, and all of them so far told me "I like your toolchain, but I know best how to manage my assets." Which I think makes a lot of sense.
• There are so many ways to organize its graphics assets? Are you using tools like Aseprite? Your own tools? What about maps? Tiled? something else?

So to my last point, the majority of the tools out there have ways to export their data as json or similar, and there are python script out there to process those export.

Right now my state of mind is that the devkit lacks a tool to automatically allocate the position of a GFX asset in the CROM/SROM, and generate a #define for your C-code. What the asset is or how you organize it, should be up to you.

I'm thinking of adding a tool that in spirit would do what we already have for music and SFX. A simple yaml file for assets. And a way to pack them into a ROM and give you offsets.

How does that sound to you?

[dciabrin]

Also I hijacked the original subject of this thread...

[dogruis]

I'm thinking of adding a tool that in spirit would do what we already have for music and SFX. A simple yaml file for assets. And a way to pack them into a ROM and give you offsets.

Would that include sprites with reversed slots in the SCB ?

For instance the main character in my case is at a reserved slot that is pretty high. And then there is other sprites. Also need to count ticks per frame and it's customisable depending on the artist.

[sasja-san]

This is from the documentation of libng:

Now, what I'm thinking isn't a parse-able bit of YAML but instead we could make a good example python script, which might cover something like the use case in the picture. That way the user could create their own classes SplitFrameSprite and FullSprite, and then run their calls to magick (or whatever they prefer) for each of these cases.

For instance the main character in my case is at a reserved slot that is pretty high. And then there is other sprites.

If it's a pretty well written python script (calling paltool and tiletool) then you should be able to tweak it this asset generation script to fit your needs.