Getting Started Improvements

[ultrasuperpingu]

I tried VUEngine and I had no problem to install it, create a template project, build it and test it. And that's pretty much what's in the Getting Started documentation. But now, I'd like to modify the template project and really, I don't really understand some basic concepts (and I feel stupid about that :( ).

The Image viewer project's readme says it allows to display 3d images without coding knowledges but I tried to add an image and I didn't find out a way to get my images "converted" to c files. The templates already contains the "Converted" folders before the build so I guess I have to do something before trying to build. Maybe a small explaination about how the asset management is working in the getting started documentation could help.

I really don't know how the build system works. There is a config.make but it seams to be generated. It seams that code added to the source folder is compiled but I think it would be useful to add a little explaination on how the build system work too.

Sorry if I missed something.

[KR155E]

Hi, ultrasuperpingu! Thanks for trying VUEngine! It's good to hear that everything worked without problems for you so far. May I ask, out of interest, which OS you are on?

The documentation is indeed lagging behind a lot, sorry about that.

I'll quickly give you a high level view of graphics in VUEngine in general here. Hopefully I'll find the time later to translate that into proper documentation. ;-)

The following isn't a complete overview, but we hope that this helps a little bit. Don't hesitate to fire any other questions and feel free to point out anything that may make the response too complex. 😛

Anyway... the main concepts used are those of states, entities and components.

States & Stages

The engine has a state machine that has to enter a user defined state at the start of the program. This is done with the line Game::start(Game::getInstance(), GameState::safeCast(AdjustmentScreenState::getInstance())); in source/game.c.

AdjustmentScreenState is the state that the engine enters when the program starts and it eventually makes the engine to enter the VueMasterState state. It is a GameState and all of these have a Stage instance, which is a Container that... contains Entities, the game entities. Stages and Entities are defined in structs called Specs (from specification), which hold the configuration values for each. For example, VueMasterState loads the stage defined by VueMasterSt.

Entities

If you check VueMasterSt's definition (in assets/stages/VueMasterStageSpec.c), you will find an array of its children (VueMasterStChildren) which contains a single child: VueMasterImage1Entity. This is the specification for the single Entity that is loaded in the VueMasterState's stage.

Sprites

By checking assets/images/VueMasterImages/VueMasterImage1/Spec/VueMasterImage1Spec.c, you will find that VueMasterImage1Entity has a list of Sprites, which are the objects used to display images, called VueMasterImage1Sprites. It is an array that holds references to 2 Sprites:

• VueMasterImage1LeftSprite
• VueMasterImage1RightSprite

A Sprite holds information about how to display a Texture and a Texture has a reference to a CharSet. All of these are abstractions of the underlying VB's graphics hardware. There are 2 Sprites because we have a stereo image, hence, 1 image for each eye.

Image conversion

VUEngine Studio uses a program called "grit" for converting images into the c files that you are asking for, containing arrays that define tiles and maps that reference those tiles. These are then used by CharSets and Textures respectively. In this example, they are VueMasterImage1Charset, VueMasterImage1LeftTexture and VueMasterImage1RightTexture.

In the assets/images folder you'll find a few .image.json files. These contain the image conversion configuration. Basically, the image converter searches for all of these files in the project and converts the images referenced under images with the given settings.

Replacing an image in VUE-Master

Let's now replace image 1 with your own. These are the steps.

Note that images must be in PNG format and should use an indexed 4-color palette in the following order: Black, Dark Red, Medium Red, Light Red. Example palettes in various formats can be found here: https://github.com/VUEngine/VUEngine-Core/tree/master/lib/palette.

1. Replace VueMasterImage1L.png and VueMasterImage1R.png in assets/images/VueMasterImages/VueMasterImage1.

2. Run the image conversion. There's a widget in the right sidepanel of the editor, which holds a button to start the conversion and lets you see some logs.

3. The engine needs to know how many tiles it has to load, so open up assets/images/VueMasterImages/VueMasterImage1/Converted/VueMasterImage1.c and copy the tile count, found in line 5, to the respective CharSetROMSpec found in assets/images/VueMasterImages/VueMasterImage1/Spec/VueMasterImage1Spec.c (line 41).

4. Build & enjoy.

Note that the VB is limited to 2048 tiles. Minus a few for the font to display the current image's number (15, I think). If your converted images require more tiles, you have to reduce visual complexity and convert again.

[ultrasuperpingu]

Great,

Thank you very much. I missed the Convert Image Panel :). I did a small gba game and the engine used grit too so I'm a little familiar with it but I didn't know how to launch it. I thought it was included in the build process...

Now I have to look closer to your explanations about stages, entities and sprite :) Seriously, your answer really helps. I think it would be useful to add this (maybe in a faq section) in your documentation. I'll try to integrate my stereo animation in the VUE-Master (I guess not before this week-end) and I'll be happy to share this experience if you will.

Thanks a lot for your help :D

EDIT: I'm using Windows 11 EDIT2: Just tried quickly, it worked. I now have to fix some issues on my images. Thanks again

[KR155E]

Awesome! I'll leave the ticket open until we incorporated the info into the docs. Maybe others will find it useful as well. :-)

[ultrasuperpingu]

Ok, great. I just had a little problem when trying to add a 50 frames animation. Default maximum is 16 frames, so I changed the maxFramesPerAnimationFunction in Engine.json and the __MAX_FRAMES_PER_ANIMATION_FUNCTION in config.h in the engine-core (and clean and rebuild). Hoping it can help somebody :)

[ultrasuperpingu]

Hi,

I post this question here because I think it's also a "Getting Started" improvement need :)

I try to get sounds in my project and I have issue to find documentation about it. I had no problem to use the files provided in example projects but how can I "compile" my own files ? For Midi, I saw in the generated files they was produced by a modified version of this software : https://www.virtual-boy.com/tools/midi-converter-and-player/downloads/ but I didn't find the "modified version". I guess I can modify the file this tool generated to get it work but if I can find the "modified version", it would be easier...

And for Wav files, I didn't find any information to know how to compile it and the documentation is empty on this subject.

Can you tell me the tools I need and where to find them ?

Thanks :)

[KR155E]

Composer tools as well as MIDI conversion tools are not ready, yet. Meanwhile, you can find the modified MIDI converter for Windows here: https://github.com/VUEngine/VUEngine-Core/blob/master/lib/utilities/MIDI-Converter.zip

For PCM sound, you need a .pcm file to convert a WAV file. The WAV file needs to be preprocessed to be mono and of a bitrate of 8 kHZ or less. Here's a sample: https://github.com/VUEngine/VUEngine-Showcase/tree/main/assets/PCM

Note that PCM is very heavy on hardware and can thus not be used during gameplay.

[ultrasuperpingu]

Thanks a lot for the quick reply :)

For PCM sound, you need a .pcm file to convert a WAV file. The WAV file needs to be preprocessed to be mono and of a bitrate of 8 kHZ or less. Here's a sample: https://github.com/VUEngine/VUEngine-Showcase/tree/main/assets/PCM

Ok, my files were stereo 44k. I switched them to mono 8k (32bits float). I tried to modify the pcm files and to close and reopen the IDE but it doesn't seem to convert it. Do I need to launch some command ?

Edit: Just tried the Midi Converter but when launching MusicPreCompiler.exe, there is no GUI and launching it in command line doesn't display usage text. I tried MusicPreCompiler.exe myfile.mid, it does log "Precompiling music for: myfile.mid" but I can't find any generated file...