Confusion with `blt` function

[edthedev]

Context

The blt function was the first thing I tried, and it appeared to fail silently. Nowhere in the documentation of blt is the need to call load with a resource file specified. And calling blt without calling load does not result in any warning or error.

[edthedev]

The existence of https://github.com/kitao/pyxel/pull/497 is the only thing that tipped me off to the true nature of the issue.

[kitao]

I understand the situation you're facing well. On the other hand, I am still thinking about how to explain it. The reason is, the blt function is an instruction to 'copy' from the image bank, and it works in any situation and will result in an error if there are invalid arguments.

The reason it seems like nothing is happening is because you are copying a 'black image bank' onto a 'black screen', so the operation is actually being executed.

Moreover, this image bank doesn't require loading to produce images. As shown in example 04, you can create pictures using the set command for definitions, or through various other APIs.

This situation is similar to sound-related commands. The play command can reproduce sound, but in its initial state, no sound is set for each sound, so 'silence' is played. So, should I write that 'to produce sound with sound commands, you need to set which sound to play'? However, I think nobody would find it strange if the sound in their head doesn't play when they use the play command without setting a sound.

Applying the same logic to images, the same principle can be stated. What was the user expecting to be displayed when they used the blt command without setting an image beforehand?

Considering this, it feels like stating that a prior load is necessary is an insufficient explanation, and a different approach or explanation is needed.

[arcade-mntra]

This explains why I was getting a black square when using the blt function while testing pyxel on pyxelstudio.net. I use TIC-80 where the spr(image_num,x,y) is sufficient to display the image from the sprite editor and was doing the same with the blt() in pyxel.

Perhaps in the "How to use" section a small code snippet could be added that demonstrates, how to load an image/sound from the sprite/sound editor and use it. Currently all three examples in the How to use section show how to draw shapes (rect, circ) but not sprites.

[kitao]

I understand the situation! People who come from environments like PICO-8 or TIC-80, where the editor and tools are integrated and only one type of resource can be used, might mistakenly think that the data created with the tool is automatically loaded.

The 'How to Use' section is intended to be as brief as possible, providing working code. It's not suitable for checking samples that prepare and load resource files.

On the other hand, at the beginning of the 'Resource Editor' section, I've already explained how to read resource data using the load function. The question now is how many people might skip this part and not read any of Pyxel's sample code at all, and to what extent we should cater to these individuals. For now, let me keep the current documentation and continue to observe how it is used.

[arcade-mntra]

The 'How to Use' section is intended to be as brief as possible, providing working code. It's not suitable for checking samples that prepare and load resource files.

Fair enough. In the blt() and bltm() section the user can be reminded of the need to load the resource for the functions to work.

I have a follow up on the pyxelstudio.net, it would make sense for the resources to be loaded automatically behind the scenes. This would make it on par with the web versions of PICO-8 or Tic-80 in ease of use for educators to introduce kids to learn python and make simple games.

[merwok]

pyxelstudio is a project separate from pyxel, you should send your suggestion to them! (email address on the website)

[arcade-mntra]

Hey, thanks for the heads up. I was unaware it was a separate project.