Dev tools: MAPeD-SPReD (win/linux)

[touko]

I agree, this is the kind of things we need .

[dogen]

I'll have to give this a shot with my next project.

[0x8bitdev]

A little update for the meta-sprite render v0.2

Optimization has been done. And added a new flag for packed sprites. See the main post for details.

The SPReD's Quick Guide has also been updated. Added information about importing images.

[lunoka]

I absolutely need to dive into this o/

[0x8bitdev]

Apr 29, 2022 16:30:49 GMT lunoka said:

I absolutely need to dive into this o/

Dive boldly, I'll help! 

[hyperfighting]

I just wanted to tip my hat to 0x8bitdev! These tools are like a dream come true! Thank you so much for all your hard work and dedication in making such awesome tools!
I played quickly and can't believe how intuitive and well designed they are! They are such a nice surprise!

I have a couple Noob questions to bug you with.

The demo programs have a warning flag built in to re-export with RLE off. Is it currently possible to export with RLE or is that still a WIP?

I have a small project I have been working on little by little year after year. I am just at the point of integrating a map so your release couldn't have come at a better time!
I believe the "multidir scrolling" is ideal for my project however I would also like too do some "static screen" stuff similar to how your Megaman demo jumps screens.
My question is if you export a "multidir scrolling" map is it possible to jump screens like in the Megaman demo if you want to do some slick screen swaps?

Thanks again!!!!!!!!!!!

[0x8bitdev]

Apr 30, 2022 23:15:07 GMT hyperfighting said:

I just wanted to tip my hat to 0x8bitdev! These tools are like a dream come true! Thank you so much for all your hard work and dedication in making such awesome tools!
I played quickly and can't believe how intuitive and well designed they are! They are such a nice surprise!

Thanks for your words! Glad you like it!

Apr 30, 2022 23:15:07 GMT hyperfighting said:

The demo programs have a warning flag built in to re-export with RLE off. Is it currently possible to export with RLE or is that still a WIP?

As for RLE... Now it's supported for the so-called 'VDC-ready' static screens. When screen data can be decompressed directly to VRAM.
To minimize RAM usage in HuC, I didn't make RLE support for multi-directional maps. Because HuC uses RAM and your map data may exceed 8K. So you may ran into a problem when your not so big, decompressed map doesn't fit into 8K RAM.

Apr 30, 2022 23:15:07 GMT hyperfighting said:

I believe the "multidir scrolling" is ideal for my project however I would also like too do some "static screen" stuff similar to how your Megaman demo jumps screens.
My question is if you export a "multidir scrolling" map is it possible to jump screens like in the Megaman demo if you want to do some slick screen swaps?

Now it isn't supported. Static screens switching is supported for bi-directional maps or for 'VDC-ready' screen data.

I can add an argument to the 'mpd_draw_screen' function for multidirectional maps - 'mpd_draw_screen( u8 _scr_ind )'. But you'll need to control adjacent screens yourself. Let me know.

[hyperfighting]

Thanks so much for the replies!

Based on what you are saying I'm thinking it is likely the most economical to design the game around your bi-directional map system! I could utilize RLE and static screen switching without the need for any additional modifications to the what you have already released.

That said the mod you mentioned would definitely be useful to have on hand!

I have been reluctant to reveal my project as I did not want to let people down with a slow drawn out development but instead I intended do something like you did and release a solid iteration all at once.
The project stems from following the legends on this forum and any forum I could find them on over the years trying my hand at coding all the while trying to keep up with new Huc versions etc.
In light of your new tools I think it best to put the project out in the world. pcengine.proboards.com/thread/1290/zuks

My intention is to entirely reformat the GFX assets for Zuks with your tools in an effort to get the most optimal setup.

I am hoping you might be able to guide me toward the best practices in using your tools and having the discussion on the open forum will hopefully serve as a guide for others looking for advice and examples using your tools.
I'm hoping the Zuks project will be a good frame of reference for those interested in following along.

Please treat me as a total noob I am not particulary well versed in the in's and out's of PC Engine Dev.

What I do understand is that space is at premium when developing for these turbo chips and I think my inital attempts at GFX may need to be rethought.

The lineage of GFX started with pushing command line arguments to the PCXTool so you will find the majority of the assets are in .pcx format and the files are not recognizable in programs like gimp and photoshop.
Turboxray helped reverse the star asset last year but I have no clue how he managed it. If anyone could help me with the process of reversing the GFX back to a readable format that would be a huge help.
The enemy assets were created last year so at least they are in a standard .png format. For the main character and enemy sprites I am using 32x32 frame sizes even though in some cases there is alot of transparent
space around the sprites. In the case of the Star Sprite Turboxray identified I should not be using a 32x32 frame size when the star does in fact fit in a 16x16 frame. At the time I was prototyping having the star in the center of the 32x32 frame helped me align it nicely with main player so thats what I did but I realize now that was a big mistake that needs to be corrected I'm curious if SPRed could help optimize the sprites in their current states. But in any case I willing to take the steps to get it right.

drive.google.com/file/d/14JJ0cxrzJkH9YcOiV1TAYqOpstBkP6YP/view?usp=sharing

[Deleted]

I think I've used MapED for NES before, nice work! I'll be definitely checking it out.

[0x8bitdev]

May 1, 2022 23:44:12 GMT hyperfighting said:

Based on what you are saying I'm thinking it is likely the most economical to design the game around your bi-directional map system!

If game maps fit the width or height of the screen, it is the best choice.

May 1, 2022 23:44:12 GMT hyperfighting said:

That said the mod you mentioned would definitely be useful to have on hand!

This modification does not violate the concept and extends the functionality. So I'll do it.

May 1, 2022 23:44:12 GMT hyperfighting said:

My intention is to entirely reformat the GFX assets for Zuks with your tools in an effort to get the most optimal setup.

I am hoping you might be able to guide me toward the best practices in using your tools and having the discussion on the open forum will hopefully serve as a guide for others looking for advice and examples using your tools.
I'm hoping the Zuks project will be a good frame of reference for those interested in following along.

I'll do my best!   Testing the toolkit on a real project is always a good experience.

May 1, 2022 23:44:12 GMT hyperfighting said:

The lineage of GFX started with pushing command line arguments to the PCXTool so you will find the majority of the assets are in .pcx format and the files are not recognizable in programs like gimp and photoshop.
Turboxray helped reverse the star asset last year but I have no clue how he managed it. If anyone could help me with the process of reversing the GFX back to a readable format that would be a huge help.

You can use any online converter to convert all your .PCX images to .PNG. For example: convertio.co. It supports converting a group of image files.
Usually I use old good photoshop cs6 for that. cs6 remembers what .PCX is. 

May 1, 2022 23:44:12 GMT hyperfighting said:

The enemy assets were created last year so at least they are in a standard .png format. For the main character and enemy sprites I am using 32x32 frame sizes even though in some cases there is alot of transparent
space around the sprites. In the case of the Star Sprite Turboxray identified I should not be using a 32x32 frame size when the star does in fact fit in a 16x16 frame. At the time I was prototyping having the star in the center of the 32x32 frame helped me align it nicely with main player so thats what I did but I realize now that was a big mistake that needs to be corrected I'm curious if SPRed could help optimize the sprites in their current states. But in any case I willing to take the steps to get it right.

The main thing is that the use of video memory is reasonable.
You have to prepare all the sprites to import into SPReD. And it's a lot of handwork. You can't get away from that. But next time you will do all the things right for importing images into SPReD.

Let's start... 

[0x8bitdev]

Let's start from the basics:

0. The main goal of using SPReD-PCE is that you can group you sprite graphics that helps you quickly switch between sprite data in your project. For example, you can move all your main menu or in-game sprite graphics to VRAM by calling a few SPD-library functions. And, of course, meta-sprites.

1. Simple sprites are sprites: 16x16, 16x32, 16x64, 32x16, 32x32, 32x64... In other words, such sprite uses ONE entry in SATB.

2. Meta-sprites in SPReD-PCE are sprites made up of many simple sprites. The SPReD-PCE supports meta-sprites export as optimal combination of various simple sprites.
BTW, simple sprites 16x32 / 16x64 must be combined with other sprites 16x32 / 16x64 to work correctly (read the Quick Guide for details).

3. The SPReD-PCE automatically exports simple sprites and meta-sprites. It depends on complexity of a sprite data.


4. SPReD-PCE helps you to prepare data for simple sprites and meta-sprites. The SPD library simplifies data initialization for both simple and meta-sprites. You'll replace all your HuC sprites initialization code with a few SPD functions.

5. You can combine simple and meta-sprites in one data set.

6. What does SPD library do with meta-sprites? It copies meta-sprites data into local SATB and transforms coordinates. Also it loads sprite graphics data and local SATB to VRAM.

7. You can use exported simple sprites with HuC sprite functions. But this resets a sprite's offset point which can be adjusted in SPReD. To avoid this, use the SPD functions for simple sprites.

SPReD:

1. First of all, please, read the SPReD's Quick Guide <F1>. Read the guide from beggining to end and try in the editor what you've read. Thus, you'll learn the interface and the basic concepts.
2. After that you need a plan!

Take your notepad and write down in it what sets of sprites will be in your project, what palette slots they will use.

For example:

In-game sprite sets:
- playable characters - 3, palette slots ~2
- enemies - 8, palette slots ~2
- bosses - 4, palette slots ~3
- bonuses - 6, palette slots 1
Main menu sprites:
- ..., ...
Interlevel sprites:
- ..., ...
Final cut sprites:
- ..., ...

You need to understand which sprite sets can be combined together, when palette slots can be overwritten by other sprite sets without conflicts.

Since you will use the SPD-render, you need to determine what sprite data is best for your purposes: static (PACKED) or dynamic (UNPACKED). Please, read here for details.
In case of simple small sprites you will use static sprite sets. If you need a lot of meta-sprites - dynamic.

This information will be updated/corrected as it becomes available. But it must be clearly defined!
By preparing sprite sets and importing them into SPReD, you will already understand the amount of data. Then you can figure out how to place them in the video memory.

There is a PCE hardware limitation when working with sprites and this is a memory alignment for sprite data.

Sort your sprites in SPReD this way to avoid glitches with displaying your sprites:

1 - Simple sprites 32x64 or 16x64 should be aligned to an address multiple of 0x0200 in VRAM <-- most biggest simple sprites first
2 - Simple sprites 32x32 or 16x32 should be aligned to an address multiple of 0x0100 in VRAM
3 - Simple sprites 32x16 should be aligned to an address multiple of 0x0080 in VRAM
4 - Simple or any custom sprites with pieces 16x16 should be aligned to an address multiple of 0x0040 in VRAM <-- all meta-sprites and simple 16x16 sprites at the end of list

SPReD-PCE doesn't sort sprites for you when importing images. This has pros and cons.

Pros: you always know sprite data order and you can manipulate with sprites in your program like with CHRs using MAPeD.
Cons: you can make mistakes... just forgot to sort them.

But in both cases you MUST use correct VRAM addresses for your sprite data.

A few words about data import.

Importing images:

a. All sprites must be stored in separate image files. You have to split all your animations into separate frames.
b. An image filename is a name of a sprite after importing into SPReD. You can import multiple images at once.
c. Take into account that HuC has a limitation on names length - no more than 47 characters. You can use 40 for sprite names.
d. When importing images, select the palette slot to which your sprites will be referenced. To avoid mistakes, it is better to import together sprites that use the same palette.

Importing images that require mirroring:

For example, we have a character that moves left/right. And we have an animation frames for the LEFT direction. The source images must not contain directional signs in their names.

a. Import all the animation frames.
b. If necessary, make the sprites aligned along axes.
c. Select sprites and make a 'Ref Copy' with postfix '_RIGHT'. The resulting sprites will share the same graphics.
d. By flipping all the copied sprites horizontally, you get animation frames for the RIGHT direction.
e. Select initially imported sprites and add them '_LEFT' postfix.

Such way you get a bidirectional sprite that shares the same graphics for both directions.

p.s.: the sample projects you can find here './samples/pce/sprite_render'
p.p.s.: Huc library file: './samples/pce/common/spd.h'
p.p.p.s: The SPD library description is here.
---------------
the content will be updated...

[0x8bitdev]

MAPeD:

1. First of all, please, read the MAPeD's Quick Guide <F1>. Read the guide from beggining to end and try in the editor what you've read. Thus, you'll learn the interface and the basic concepts.
2. After that you need a plan! 

The main thing you have to know is that a main menu in your game, interlevel cut scenes, intro, outro... All of these things are game maps in terms of editor. And game maps are game maps too!

So, your game structure in the MAPeD is a set of ordered maps.

For example, your maps or game levels in the editor may look like this ('Layout' tab ->'Layouts' list):
0 - main menu (map)
1- interlevel scene (map!)
2 - first level (...!)
3 - ...

After exporting you will switch this maps with the 'mpd_init( _map_ind )' function that takes as parameter a map number.

Take your notepad and write down the structure of your project in it. What scenes are in it and how best to organize and arrange them in the editor.

A good practice is to test step by step what you have done in your test application. This way you will immediately fix potential problems.

MAPeD & HuC:

Bi-directional map:

- Bi-directional map is a map with seamless fullscreen scrolling left/right/up/down.
- Usually this map describe a certain trajectory in one layout.
- A trajectory of a bi-directional map can be described as a straight or broken line.

NOTE: A special case of bi-directional map is a map with a line of screens (vertcal or horizontal).
NOTE: Start screen must be defined for all maps in the editor, otherwise the first active screen will be defined as a start one;

Mpd-render (MAPeD's tilemap render for HuC) implementation features:
- Displaying a map from a start screen defined in the editor;
- Displaying a map from any screen;
- Displaying a map at any free position isn't available(!);
- Scene movement from screen to screen with a seamless scrolling along a map left/right/up/down;
- Use of 'adjacent screen masks' that describe a special trajectory;
- Tile properties detection by X, Y position within a screen space;

Exported data:
A bi-directional map is a linked array of unique screens with no duplicates (so, this is an option for minimizing exported data size).
Each screen is a row\column ordered array of tile indices.

Pros:
1. A little faster than unified for any map size 'MULTI-'.
2. Exported data size can be reduced with duplicated screens in your map.

Cons:
1. A map can not be displayed at any free position, per screen only (by a screen data pointer). You can't center object on the screen.
2. A more complicated algorithm for detection of a tile property.


Multi-directional map:

- Multi-directional map is described as rectangular area filled with screens.

NOTE: A special case of multi-directional map is a map with a line of screens (vertcal or horizontal).
NOTE: Start screen must be defined for all maps in the editor, otherwise the first screen will be defined as a start one;

Mpd-render implementation features:
- Displaying a map from a start screen defined in the editor;
- Displaying a map from any screen;
- Displaying a map from any X, Y position;
- Free scene movement at any direction within a map;
- Tile properties detection by X, Y position within a map space;

Exported data:
A multi-directional map is a simple MxN row\column ordered array of tile indices.

Pros:
1. A map can be displayed at any free position by X, Y and per screen (by a screen index 0-N).
3. A tile properties detection algorithm is faster than with 'BI-'.

Cons:
1. A little bit slower than 'BI-'.
2. ...?


LIMITATIONS:

1. A Bi-directional and a multi-directional map MUST use only ONE CHR bank!
Using screens from a multiple data banks in one map are not allowed!
The only exception to the rule is a bi-directional map with static screens switching (without scrolling!). Such bi-directional maps can use screens from any CHR banks.

2. The Mpd-render uses either bi-directional or multi-directional maps as input data. Mixing of different types of maps in one HuC project are not allowed at the moment!
But with a reasonable design of your maps this limitation can be bypassed.

p.s.: the sample projects you can find here: './samples/pce/tilemap_render'
p.p.s.: Huc library file: './samples/pce/common/mpd.h'
p.p.p.s: the MPD library description in the next post
-----------------
the content will be updated...

[0x8bitdev]

0. BEFORE USING THE LIBRARY, READ THE PCE OFFICIAL/UNOFFICIAL HARDWARE DOCUMNETATION TO UNDERSTAND HOW PCE HARDWARE WORKS

The tilemap library

History:

v0.9

Dynamic tilemaps:
~~~~~~~~~~~~

The information below applies mainly to multi-directional maps.

By default, all maps data are stored in ROM. Accessing them requires constant switching of memory banks.
This can be avoided by placing the map data in RAM. This greatly speeds up data access and gives new features such as dynamically changing map and tile properties.

Dynamic map changing can be used to change map topology, procedural generation of levels, also it's fastest way for storing collectable items etc...

There are three types of data that can be located in RAM:

- tilemap data
- tilemap LUT
- tile properties

This data can be initialized into RAM independently of each other. It all depends on the amount of free RAM available.

You can do this by placing the following declarations before the MPD library is included in your program:

#define MPD_RAM_MAP
#define MPD_RAM_MAP_TBL
#define MPD_RAM_TILE_PROPS <-- can be used with any type of maps(!)

All these defines speed up getting a tile property and slightly speed up static screens drawing and scrolling.

MPD_RAM_MAP - enables the following functions:

[macro] u8 mpd_get_tile( u16 _x, u16 _y, bool _pixels ) / _pixels = TRUE - pixel coordinates, FALSE - tile coordinates
[macro] void mpd_set_tile( u16 _x, u16 _y, bool _pixels, u8 _tile_ind ) / _pixels = TRUE - pixel coordinates, FALSE - tile coordinates, _tile_ind - 0..255

MPD_RAM_TILE_PROPS - enables the following functions:

#if FLAG_PROP_ID_PER_CHR

[macro] u8 mpd_get_tile_property( u8 _tile_ind, u8 _CHR_ind ) / _tile_ind - 0..255, _CHR_ind - 0..3
[macro] void mpd_set_tile_property( u8 _tile_ind, u8 _CHR_ind, u8 _new_prop ) / _tile_ind - 0..255, _CHR_ind - 0..3, _new_prop - a new property value

#else //FLAG_PROP_ID_PER_BLOCK

[macro] u8 mpd_get_tile_property( u8 _tile_ind ) / _tile_ind - 0..255
[macro] void mpd_set_tile_property( u8 _tile_ind, u8 _new_prop ) / _tile_ind - 0..255, _new_prop - a new property value

#endif //FLAG_PROP_ID_PER_CHR

By default, implementations of these functions are unsafe. You can write data outside the arrays by mistake.
Use MPD_DEBUG when developing, to enable safe function implementations. If you write data outside of the allocated memory, you will get an error message, function name and its arguments.

The amount of memory that will be allocated for the data can be seen in <my_exported_tilemap>.h

#define MAX_MAP_SIZE ...
#define MAX_MAP_TBL_SIZE ...
#define MAX_TILE_PROPS_SIZE ...

NOTE: If several maps are exported, memory will be allocated for the largest map(!)

Transferring this data to RAM will have a positive effect on performance, even if you don't intend to use dynamic maps and tile properties features.
It all depends on the amount of free RAM in your project and the size of your maps. The size of a map can far exceed the amount of available RAM.
So plan and allocate memory in your project carefully to effectively use the MPD library.

There are two example projects that demonstrate dynamic maps functionality:

Simple map editor:
./samples/pce/tilemap_render/multidir_scroll_map_editor/

Procedural generation of a random maze (3x3 screens):
./samples/pce/tilemap_render/multidir_scroll_maze_generator/

NOTE: Dynamic maps support RLE-compression.

Getting a tile property with dynamic maps:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From the available functionality of dynamic maps follows a more flexible way to obtain a tile properties for multi-directional maps.
For example, when both tiles and tile properties consist of 2x2* blocks, you can use:

mpd_get_tile_property( mpd_get_tile( x, y, TURE/FALSE ) ) **

This will work faster than mpd_get_property( x, y ), due to its greater versatility.

But if you have a simple map consisting of 2x2 blocks or 4x4 tiles with unique properties per tile (when different tiles do not share the same property),
then the built-in tile property data can be ignored and replaced with block/tile indices.
In this case, getting the properties of a tile is reduced to a single call to mpd_get_tile( x, y, TRUE/FALSE ), which is even faster.
------
* It is more complicated with 4x4 tiles, because they require additional data about the 2x2 blocks of which they are composed.
And this data is in ROM. In this case it is easier to use the existing function mpd_get_property( x, y ).

** Since mpd_get/set_tile_property(...) and mpd_get/set_tile(...) are macros or inline functions, and if you have many identical calls to them in your code, it may be better to wrap these calls with function(s).

New read-only public variables are also available:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Map width/height in tiles:

R: u16 mpd_map_tiles_width
R: u16 mpd_map_tiles_height

Size of the tile properties array of a current map when declaring the MPD_RAM_TILE_PROPS:

R: u16 mpd_tile_props_arr_size

ASM MPD_DEBUG changed to HuC '#define MPD_DEBUG'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


v0.8
- reduced the number of HuC functions (.proc/.endp):
    [#define] mpd_get_curr_screen_ind()
    [#define] mpd_clear_update_flags()
    [#define] mpd_copy_screen(...)
    [#define] mpd_get_map_size(...)
    [#define] mpd_get_start_screen(...)
    [#define] mpd_init_base_ent_arr()
    [#define] mpd_get_base_ent_cnt()
    [#define] mpd_draw_screen_by_ind(...)
    [#define] mpd_draw_screen_by_data(...)
    [#define] mpd_draw_screen()
    [macro] mpd_load_palette(...)
- optimized use of local variables and function arguments

v0.7
- updated 'Working with screens/entities - General information' / item 2
- added 'mpd_get_curr_screen_ind()' for multidirectional maps
- added open variables to replace deprecated functions
- fixed missed tile 4x4 drawing for scrollable maps and also fixed BAT overflow in some cases in 'mpd_draw_screen(...)'
- optimized screen scrolling, re-written in assembler; 3x faster than before
- added 'mpd_get_scroll_step_x'/'mpd_get_scroll_step_y'
- renamed 'mpd_scroll_step_x'/'mpd_scroll_step_y' to 'mpd_set_scroll_step_x'/'mpd_set_scroll_step_y'

Open variables and deprecated functions:
~~~~~~~~~~~~~~~~~~~~~~~~~~~

#if FLAG_MODE_BIDIR_SCROLL

R: mpd_SCR_DATA mpd_curr_scr -> mpd_curr_screen() - DEPRECATED

#endif //FLAG_MODE_BIDIR_SCROLL

#if FLAG_MODE_MULTIDIR_SCROLL

Map width/height in screens:

R: u8 mpd_map_scr_width
R: u8 mpd_map_scr_height

Active map width/height in pixels = map width/height in pixels - screen width/height in pixels

R: u16 mpd_map_active_width -> mpd_active_map_width() - DEPRECATED
R: u16 mpd_map_active_height -> mpd_active_map_height() - DEPRECATED

#endif //FLAG_MODE_MULTIDIR_SCROLL

#if FLAG_MODE_MULTIDIR_SCROLL + FLAG_MODE_BIDIR_SCROLL

Map scrolling step in the range 0..7

RW: u8 mpd_scroll_step_x [0..7] -> mpd_get_scroll_step_x()/mpd_set_scroll_step_x(...) - DEPRECATED
RW: u8 mpd_scroll_step_y [0..7] -> mpd_get_scroll_step_y()/mpd_set_scroll_step_y(...) - DEPRECATED

Map scrolling values:

R: s16 mpd_scroll_x -> mpd_scroll_x() - DEPRECATED
R: s16 mpd_scroll_y -> mpd_scroll_y() - DEPRECATED

#endif //FLAG_MODE_MULTIDIR_SCROLL + FLAG_MODE_BIDIR_SCROLL

*R-read only; RW-read/write
--------------------------------------------
Replace the deprecated functions with the global variables. And don't write to read only variables.


v0.6
- screens/entities data moved from H file to ASM to save more memory for user data
- added HuC functions to get access to screens/entities data
- added description how to work with screens/entities
- added MPD_DEBUG flag that shows how long screen drawing/scrolling takes by border colors (use Mednafen); it is disabled by default in all samples, uncomment 'MPD_DEBUG' to enable the debug mode


Debug info (use Mednafen):

- green border color - screen scrolling
- blue border color - static screen drawing
- yellow border color - getting a tile property

Place this before '#include "mpd.h"':

#asm
MPD_DEBUG
#endasm


Working with screens/entities:

General information:

1. Regardless of a map type, all entities data is stored in screens.
2. The maximum number of allowed entities per screen is 255. But the maximum number of allowed entities per map is 256.
3. There are base entities and instances. The base entities you customize in MAPeD in the 'Entities' tab. The instances are base entities that have been placed on a map.
4. Entities can be sorted during the data export process in two ways: left to right or bottom to top. The sorting goes by pivot points.
5. So, for a multi-directional map, whichever screen you take, you will always have sorted entity data.
6. Accessing screen/entity data requires banks switching and data copying. So it is recommended to cache the data in optimal way for your project when initializing a map data.

Data structures:

typedef struct
{
u8 id;
u8 width;
u8 height;
u8 pivot_x;
u8 pivot_y;
u8 props_cnt;

} mpd_ENTITY_BASE;

typedef struct
{
u8 id;
u16 base_ent_addr; // for library use only
u16 targ_ent_addr; // for library use only
u16 x_pos;
u16 y_pos;
u8 props_cnt;

} mpd_ENTITY_INSTANCE;

typedef struct
{
mpd_ENTITY_INSTANCE inst;
u8 inst_props[ ENT_MAX_PROPS_CNT ];

mpd_ENTITY_BASE base;
u8 base_props[ ENT_MAX_PROPS_CNT ];

} mpd_ENTITY;

typedef struct
{
mpd_PTR24 scr_arr_ptr; // for library use only
u16 scr_offset; // for library use only

mpd_SCREEN scr; // depends on exported options, see exported .h file for details

#if FLAG_ENTITIES
mpd_ENTITY inst_ent;
mpd_ENTITY targ_ent;
#endif //FLAG_ENTITIES

} mpd_SCR_DATA;


The functions for accessing base entities:

void    mpd_init_base_ent_arr() - must be called once for all maps(!)
u16    mpd_get_base_ent_cnt()
void    mpd_get_base_entity( mpd_SCR_DATA* _scr_data, u16 _ent_ind ) - RES: _scr_data->inst_ent.base

Examples of using the library for multi-dir maps:

void    mpd_init_screen_arr( mpd_SCR_DATA* _scr_data, u8 _map_ind ) - must be called once for each map(!)

Getting a map size in screens:

u16 map_size;
u8 scr_width;
u8 scr_height;

map_size = mpd_get_map_size( map_ind );

scr_width = map_size & 0x00ff;
scr_height = ( map_size & 0xff00 ) >> 8;

or for a current map use these global variables:

mpd_map_scr_width
mpd_map_scr_height

Accessing screen/entity data:

mpd_SCR_DATA scr_data;

u8 scr_cnt;
u8 scr_n;
u8 ent_n;

scr_cnt = mpd_map_scr_width * mpd_map_scr_height;

for( scr_n = 0; scr_n < scr_cnt; scr_n++ )
{
mpd_get_screen_data( &scr_data, scr_n );

for( ent_n = 0; ent_n < scr_data.scr.ents_cnt; ent_n++ )
{
mpd_get_entity( &scr_data, ent_n );

AND/OR

if( mpd_find_entity_by_base_id( &scr_data, base_ent_id ) )
{
...
}

AND/OR

if( mpd_find_entity_by_inst_id( &scr_data, inst_ent_id ) )
{
...
}

...
}
}

Examples of using the library for bi-dir maps:

Use 'mpd_curr_scr' to access the current screen, but make a copy 'mpd_copy_screen( mpd_SCR_DATA* _src_scr, mpd_SCR_DATA* _dst_scr )' before using 'mpd_get_screen_data( mpd_SCR_DATA* _scr_data, u16 _scr_ind )'

Iterating a map screens:

u16 adj_scr;
mpd_SCR_DATA scr_data;

mpd_get_start_screen( &scr_data );

// getting adjacent screen by input direction
adj_scr = mpd_get_adj_screen( &scr_data, ADJ_SCR_LEFT/ADJ_SCR_RIGHT/ADJ_SCR_UP/ADJ_SCR_DOWN );

if( adj_scr != 0xffff )
{
mpd_get_screen_data( &scr_data, adj_scr );
...
...

Accessing entities:

u8 ent_n;

mpd_curr_scr <- read only!

OR

mpd_SCR_DATA scr_data;
mpd_get_start_screen( &scr_data );

for( ent_n = 0; ent_n < scr_data.scr.ents_cnt; ent_n++ )
{
mpd_get_entity( &scr_data, ent_n );

AND/OR

if( mpd_find_entity_by_base_id( &scr_data, base_ent_id ) )
{
...
}

AND/OR

if( mpd_find_entity_by_inst_id( &scr_data, inst_ent_id ) )
{
...
}

...
}


v0.5
- removed 'mpd_draw_screen_by_pos_offs' as unsafe and useless
- 'mpd_draw_screen_by_ind' and 'mpd_draw_screen_by_ind_offs' - changed screen index from u16 to u8
- fixed scroll values overflow in the 'mpd_move_right/left/up/down' for multi-dir mode

Added tile drawing functions:

IN:    _x, _y - screen space coordinates in pixels
        _block2x2_ind - 0..255
        _CHR_ind - 0..3

void mpd_draw_CHR( u16 _x, u16 _y, u8 _block2x2_ind, u8 _CHR_ind )

IN:    _x, _y - screen space coordinates in pixels
        _block2x2_ind - 0..255

void mpd_draw_block2x2( u8 _x, u8 _y, u8 _block2x2_ind )


For maps with 4x4 tiles:

IN:    _x, _y - screen space coordinates in pixels
        _tile4x4_ind - 0..255

void mpd_draw_tile4x4( u8 _x, u8 _y, u8 _tile4x4_ind )

NOTE: For scrollable maps add 'mpd_scroll_x' to _x and 'mpd_scroll_y' to _y


v0.4

1. Added support for free step scrolling (1-7 pixels per step). It can be used for inertial scrolling.

    Removed 'mpd_scroll_step' enum, now 'mpd_init( u8 _map_ind, u8 _step )' as scroll step value receives numbers 1-7 pix.
DEPRECATED -> Added 'mpd_scroll_step_x( u8 _step_pix )/mpd_scroll_step_y( u8 _step_pix )' for scrollable maps.

DEPRECATED -> mpd_scroll_step_x( calced_positive_move_step ); use the 'mpd_scroll_step_x'/'mpd_scroll_step_y' variables
mpd_move_left();

2. 'mpd_draw_screen_by_scr_ind' renamed to 'mpd_draw_screen_by_ind'.
'mpd_draw_screen_by_scr_data' renamed to 'mpd_draw_screen_by_data'.

3. Added 'mpd_draw_screen_by_ind_offs( u16 _scr_ind, u16 _BAT_offset, bool _reset_scroll )' for multi-directional mode.
Added 'mpd_draw_screen_by_data_offs( mpd_SCREEN* _scr_data, u16 _BAT_offset )' for bi-directional maps.

This allows to draw screens at any place in BAT and can be used for various purposes:

    a. For double-buffered screen switching without black screen ( disp_off()/disp_on() ) within one map.
    Added a new sample that shows double-buffered screen switching for multi-directional maps: './samples/pce/tilemap_render/multidir_stat_scr_multimap'

    b. For custom scrolling between screens out of the tilemap library. The same technique as (a), but you can make your custom scrolling between screens.

    c. If your game map fits into any BAT size, you can fill the BAT with a map screens and make a map scrolling using the way described in point 4 (see below).
    It's faster than using the tilemap library for scrolling!
    So, the rule is as follows: if each of your game maps fits into BAT, DON'T USE the MPD library for scrolling! It doesn't make any sense! Use it for filling BAT with screens and getting a tile property!

4. Removed VDC's scroll registers update on 'mpd_init' and 'mpd_update_screen'.
'mpd_update_screen( bool _vsync )' changed to 'mpd_update_screen()'.

    Since v0.4 the library doesn`t interact with VDC`s scroll registers in any way! It just provides scroll values X/Y: mpd_scroll_x, mpd_scroll_y.
    Thus, user must set scroll values in his program using these global variables. This is for scrollable maps only!

    There are two ways:

    1. Fullscreen scrolling. Write directly to the bgx1(0x220c)/bgy1(0x2210) system variables:

for(;;)
{
...your code here...

// update VDC's scroll registers on VBLANK via bgx1/bgy1 variables
pokew( 0x220c, mpd_scroll_x );
pokew( 0x2210, mpd_scroll_y );
vsync();
}

    2. Area scrolling. If you need to combine a static HUD and the scrollable area for your map, you can do this using the HuC's scroll library - 'scroll(...)':

    NOTE: This will work for linear horizontal bi-directional maps!

// init HUD out of the visible BAT area
scroll( 0, 0, 224, 0, 31, 0x80 );

for(;;)
{
...your code here...

// map scrolling
scroll( 1, mpd_scroll_x, 32, 32, 223, 0xC0 );
vsync();
}

    Thus, the main option is (1). But if you need to limit the scrollable area you need to use the (2) option.

    NOTE: To avoid conflicts, these options can not be used together. You must use either (1) or (2).

-------------------------------------------------------------------------------------------------------------------------
P.S.: See example projects for details: './samples/pce/tilemap_render'.
P.P.S.: All the changes and updated samples you can find in the dev build archive.

[hyperfighting]

Sooooo I'm overwhelmed in the best possible way! I'll try to write this in a format that is hopefully somewhat interesting to read 

Today there were two options on one hand sprites and on the other the map.

Weighing these options my rationale was there are several sprites and one map so I should see if I can slip the new map over top of the old one and see what happens.

I had already played a little in MAPeD so I figure might as well start here.

My original map was loaded into MAPeD from my tinkering a day or two ago.

Ok step 1. says we must read the help. Upon opening MAPeD I hit F1 and started reading. In my research I learned "Tiles(4x4) are the most compact way to store screen data." so that led me to say how do I do that? 

I noticed by default MAPed has 2x2 blocks selected (aka 16x16 tiles) Upon switching to 4x4 a whole new world opens up! You can create any combination of 4x4 tiles and paint your screens with them!!!!!!
I can only guess that because you are using larger tiles the index is somehow smaller to store. Dope Sauce. I digress.  BUT then something nuts happened MAPeD gives you the option to automatically create 4x4 tiles from the source image on import.!!!!!! My head suddenly exploded like a pizza pocket commercial after I clean up the guts I got to work on a revised version of the source file containing all kinds of 4x4 tile combinations! I thought why not have them prebuilt in the source file before initially importing it saves me building them in MAPeD but If forget some MAPeD has me covered and will let me build them!!!!!!!!

Building the Map took the better part of the day. In the past we had Crappy (joking) I mean Mappy. The Zuks prototype featured in the YouTube video uses the export from promotion. I was so happy regarding the promotion integration in HuC because I could finally get a Map into the project! I tried so hard with Mappy and always failed doh. In the past I also used the i2pce utility as way of attempting to get a colourful map in there. The reason I mention all these methods is because there was one secret sauce I used to finally get the map out of promotion some may know this amazing utility I did not and when I found it man was I happy "tilequant" that's right  I said it one of the most gangsterest applications of the 21st century this program will create organized palettes out of your image!!!!! How I struggled 1. Python (Not the snake the computer language) 2. Command line 3. The new version (At the time) seemed to have removed 16x16 tile support so I dug for an old version. At the time the new version was natively pushing that 8x8 tile love exclusively. Once I had tilequant installed and the parameters "tilequant [OPTIONS] INPUT_IMAGE -w 16 -h 16 OUTPUT_IMAGE" I was gold to export my file out of ProMotion baby. I felt like I had cracked the Rosetta stone or something man was that solid to have multi palette backgrounds loading up on the PCE!  

So then I started importing my source image into MAPeD (source image needs to be index colour and in .bmp format) and MAPeD already has me covered! I can totally cut "tilequant" out of the picture!!!!!!! MAPeD also has a provision for ordered palettes on import so you are covered in either case! The reason I mention "tilequant" is it still could be useful...The thought comes to mind of cycling palettes etc (Maybe I'm ahead of myself but I know there is definitely a time and a place for ordered palettes and "tilequant" is a pretty handy app if not a little involved for some to get setup) In my case I am overjoyed that MAPeD can help skip that step and help get the palettes in there without a headache.

I spent alot of time Importing the new source image into MAPeD. In the end my final settings are:



Everytime I wanted to reimport my source image I literally closed and reopened the MAPeD app (Sorry I have a degree in denseness) Then I came to realize there is a BANK- button doh.

Before you can import anything you need a BANK so literally turn MAPeD on and press the BANK+ button to create BANK 0 then you are free to import.

Every import had something wrong with it. Too many tiles! Duplicate Tiles! Useless Tiles! I quickly became obsessed and felt like I was Golem when it came to tiles "You are all my pretties! And pretty you are!" Yada finally a map I like.



I will attempt to explain what's what....Wait look at that ugly thing there are so many redundancies!? YUP and MAPeD optimizes them perfectly! No duplicate tiles here!
If you direct your attention to the bottom right at first glance chaos and non sense but remember the 4x4 tile blocks? that little mess is my first attempt at precapturing all the 4x4 combinations I might want and they will be automatically ready to go in MAPeD 4x4 mode!

So this map is broken into 256x224 screens but I noticed MAPeD will let me assign other heights and widths. The prototype is in 256x224 but I guess it's now or never should I consider another resolution? Perhaps 320x224?
Any input would be greatly appreciated. (I kinda want to keep it 256x224 just cause I spent a day on this Map but it shouldn't be to hard to reformat at this stage if that's what should be done....bigger playing field etc )

So the Zuks! prototype has two screen swaps in it. The title screen has the Zuks! Text in sprites overplayed on the blank screen at the point the text raises the sprites are removed and the full Zuks! image appears.
Another swap is the mountain with and without tiles dividing it. The unique thing is the Mountain on the left is between two screens for placement in the introduction to the PLAYER SELECT screen. As long as my X,Y coordinates are divisible by 16 I should be able to overlay the second Mountain in seamlessly (Hoping).

A final note I am hoping the pink can be a transparent colour and the turbo can make a nice blue background colour. If this is possible the tiles can be on different background colours without altering the palettte. (I think)

So I tried my hand at starting a Layout that describes how the flow of the game would work. 

The Layout is 4x10 screens (The top two rows is where all the action would happen Space and AIR)
The bottom two rows are where you fall to die and respawn from. The thought crossed my mind what if I wanted to lengthen or shorten the existing layout is that possible or do I have to create a new layout and replace the maps and the markers?



Well that's it for me that's it for me all that talk and still no programming Eh!? Yeah I guess tomorrow is another Map day I'm going a bit batty =) Hope what I'm writing makes sense.




 

[0x8bitdev]

May 3, 2022 2:42:23 GMT hyperfighting said:

Sooooo I'm overwhelmed in the best possible way! I'll try to write this in a format that is hopefully somewhat interesting to read 

BTW, the guide from user point of view is a good idea!
For me as a for developer everything is clear. If I start writing basic things here, I'll just duplicate the quick guides. If you've read the guides and have tried what you've read, the more efficient way to exchange information would be "question - answer". 

May 3, 2022 2:42:23 GMT hyperfighting said:

Ok step 1. says we must read the help. Upon opening MAPeD I hit F1 and started reading. In my research I learned "Tiles(4x4) are the most compact way to store screen data." so that led me to say how do I do that? 

I noticed by default MAPed has 2x2 blocks selected (aka 16x16 tiles) Upon switching to 4x4 a whole new world opens up! You can create any combination of 4x4 tiles and paint your screens with them!!!!!!
I can only guess that because you are using larger tiles the index is somehow smaller to store. Dope Sauce. I digress.  BUT then something nuts happened MAPeD gives you the option to automatically create 4x4 tiles from the source image on import.!!!!!! My head suddenly exploded like a pizza pocket commercial after I clean up the guts I got to work on a revised version of the source file containing all kinds of 4x4 tile combinations! I thought why not have them prebuilt in the source file before initially importing it saves me building them in MAPeD but If forget some MAPeD has me covered and will let me build them!!!!!!!!

Building the Map took the better part of the day. In the past we had Crappy (joking) I mean Mappy. The Zuks prototype featured in the YouTube video uses the export from promotion. I was so happy regarding the promotion integration in HuC because I could finally get a Map into the project! I tried so hard with Mappy and always failed doh. In the past I also used the i2pce utility as way of attempting to get a colourful map in there. The reason I mention all these methods is because there was one secret sauce I used to finally get the map out of promotion some may know this amazing utility I did not and when I found it man was I happy "tilequant" that's right  I said it one of the most gangsterest applications of the 21st century this program will create organized palettes out of your image!!!!! How I struggled 1. Python (Not the snake the computer language) 2. Command line 3. The new version (At the time) seemed to have removed 16x16 tile support so I dug for an old version. At the time the new version was natively pushing that 8x8 tile love exclusively. Once I had tilequant installed and the parameters "tilequant [OPTIONS] INPUT_IMAGE -w 16 -h 16 OUTPUT_IMAGE" I was gold to export my file out of ProMotion baby. I felt like I had cracked the Rosetta stone or something man was that solid to have multi palette backgrounds loading up on the PCE!  

So then I started importing my source image into MAPeD (source image needs to be index colour and in .bmp format) and MAPeD already has me covered! I can totally cut "tilequant" out of the picture!!!!!!! MAPeD also has a provision for ordered palettes on import so you are covered in either case! The reason I mention "tilequant" is it still could be useful...The thought comes to mind of cycling palettes etc (Maybe I'm ahead of myself but I know there is definitely a time and a place for ordered palettes and "tilequant" is a pretty handy app if not a little involved for some to get setup) In my case I am overjoyed that MAPeD can help skip that step and help get the palettes in there without a headache.

Ha-ha-ha-ha... It's a real blockbuster!!!1...

May 3, 2022 2:42:23 GMT hyperfighting said:

I spent alot of time Importing the new source image into MAPeD. In the end my final settings are:

<button disabled="" class="c-attachment-insert--linked o-btn--sm">Attachment Deleted</button>

As for the 'Skip zero CHR\Block' options... By default, all the CHRs\Blocks\Tiles are zero-filled arrays. So, all the blocks data are linked to the zero character in CHR bank and all the tiles data are linked to the zero block (all zeros). But, after importing, when that zero character in CHR bank is filled with some tile, you'll see that character in all unused blocks and tiles. Thus, all your unused data will be filled with "abrakadabra" or with the first character in a CHR bank.

This option just helps to make things clear. It reserves the first character in CHR bank and the first block 2x2 and all your unused blocks\tiles look empty. You can see where your data ends.
That reserved character and block may be deleted during the optimization process.

May 3, 2022 2:42:23 GMT hyperfighting said:

Everytime I wanted to reimport my source image I literally closed and reopened the MAPeD app (Sorry I have a degree in denseness) Then I came to realize there is a BANK- button doh.

Before you can import anything you need a BANK so literally turn MAPeD on and press the BANK+ button to create BANK 0 then you are free to import.

You are right. The first message in status bar that you can see after running the MAPeD talks about screen dimensions for your project and this button. There is no need to click the 'Bank+' button only when you load a project.

May 3, 2022 2:42:23 GMT hyperfighting said:

So I tried my hand at starting a Layout that describes how the flow of the game would work. 

The Layout is 4x10 screens (The top two rows is where all the action would happen Space and AIR)
The bottom two rows are where you fall to die and respawn from. The thought crossed my mind what if I wanted to lengthen or shorten the existing layout is that possible or do I have to create a new layout and replace the maps and the markers?

Actually, your layout looks strange... Could you please send me a reference game that 100% reflects your ideas, so that I could suggest something.

p.s.: You can use the MAPeD version from the development build. The latest version has optimized map rendering. Now it's a much faster.