Terevaka - a high level framework on Lua for mobile platforms
Dear friends, today I will tell you about the high level framework on Lua for mobile platforms of its own design. As you have probably guessed from the name, this framework uses another low-level framework for drawing graphics and for interacting with the system. The quality of it is MOAI. For a minimum familiarization with it, I recommend reading my previous article habrahabr.ru/post/176765
First of all, what tasks should the new framework perform?
First, the problems with the fragmentation of screens. And secondly (ta-dam), I wanted to have some kind of, even the simplest, graphical interface editor. Third, the framework had to define the architecture and file structure of the application as a whole. I want to say that the code turned out a bit (less than 600 lines), so even if the framework does not suit you, as it is, it will be easy to deal with its work and sharpen it for your needs.
Warning: the framework is sharpened under the landscape of the application, so if you need portrait mode, you will most likely have to spend some time on revision.
Let's go back to the fragmentation of the screens.
To solve the problem of fragmentation, the application needs to take into account:
In order to solve all these three tasks in one fell swoop, Corona SDK or Gideros suggest choosing the scaling policy of the entire application. The most adequate of these modes is the so-called letterbox. This is when the application is uniformly scaled to fit the screen, but there are black bars along the edges in case of a mismatch of proportions.
In MOAI, as such, there is no mode, but there are snapshots of how to implement this in a few lines by manipulating the viewport parameters.
It is clear that such a half-measure cannot satisfy a really good application. The screens of mobile devices are already small, so that even their area is eaten by black stripes.
Obviously, we cannot do without an elastic layout (we solve the problem of dimensions / proportions).
As for the different screen resolutions, this is easily solved by a set of different graphics or its scaling. However, in Android / iOS, these mechanisms work in different ways, so you have to implement it yourself.
')
A graphical editor was written using PyQt. It is quite simple and can only manipulate sprites, I mean pictures.
MOAI supports text display, but neither the graphics editor nor Terevaka can display it. In practice, this means that if you need to apply text on top of the button, then you need to do it programmatically after the button sprite is loaded (or put the text directly on the button sprite, lol).
Nevertheless, the graphic editor is a powerful tool, since it allows not only to place elements graphically, but also to separate the view from the program logic.
The graphical editor stores the project file in a JSON file and exports the layer to the internal representation of Terevaka (Lua file) on the principle of one file - one layer.
Layers are of two types: elastic and scalable.
Elastic layer when displaying places elements depending on the sides of the binding. Those. If you want the element to follow the upper right corner when scaling, you need to specify the coordinates relative to this angle.
Example layer in editor:
Iphone 3.5 Inch:
Iphone 4 inch:
IPad:
A scalable layer is a different type of layer that scales proportionally, like letterbox. For example, the main menu makes sense to do it with the help of a scalable layer, but the background, however, is better done on the whole screen.
Example layer in editor:
Iphone 3.5 Inch:
Iphone 4 Inch:
IPad:
In the editor, the proportions of the scalable layer are fixed 427x320. These are the proportions of the iPad, reduced to the size of the iphone. You can choose more convenient parameters for yourself, but you need to remember about the resolution of the graphics that will be used in the designer and directly in the application. For myself, I use 853x640 (I need to change the parameter directly in the source code of the graphical editor) and upload retina to the editor. In the application itself, as a rule, I use even higher resolution textures so that the graphics match the large retina screens, and during the layer loading I specify the dpiMultiplier parameter so that the sprites load in the right size.
The reason why I use hard-coded 427x320 portions is that it's easy to get confused with sizes / resolutions, so who understands what's what, will figure out how to adapt it for your own case.
So, combining approaches, you can quickly create flexible graphics.
Files with layers are stored in the ./res/layout/ directory by analogy with Android.
Different screen resolutions are supported by a double set of graphics.
A set of graphics with the usual resolution is stored in ./res/drawable-mdpi/, and the retina is stored in ./res/drawable-xhdpi/. If the screen resolution does not match one of these, then the most suitable set will be taken and scaled. Directories ./res/drawable-ldpi and ./res/drawable-hdpi are not yet supported by the engine.
The important point is that when loading a layer, it is advisable to use packed sprites in one texture in order to optimize the amount of memory consumed. The framework supports MOAI format, which can convert paid TexturePacker.
Warning: do not use texture wrapping in TexturePacker with removal of empty areas, as there is a bug in the exporter in MOAI format and the graphics will eventually float.
To get a sprite from a layer, use the findPropById function (again, the analogy with Android)
To handle clicking on the sprite, it is enough to attach a special callback (see an example in terevaka-samples).
For other various usage examples, see the terevaka-samples project. To run the example, copy tereavaka to the example folder, or better yet, make a symlink into it.
To test the application under different screens, you do not need a lot of different devices at all - use launch profiles. The finished profiles are in the directory ./terevaka/profiles.
To run with a profile, use the moai ./terevaka/profiles/ipad.lua main.lua command, where ipad.lua is the ipad profile. The profile is usually 3-4 lines, you can easily create your own profiles.
Sprites for ui builder need to be saved in mdpi resolution.
Initially, the project began as the selection of some common code from the code of my new game. In an attempt to structure, both the code itself and its requirements led to the emergence of the framework, and then, using my old ideas, and the graphic designer to it. In addition, MOAI itself had to be refined, but thanks to the quick response of its developers, all changes have already been made to the main repository.
Also - this is a demonstrative experience that you should not be afraid to write your libraries, if you clearly understand the requirements for them, and also if you write in the scripting language :)
Terevaka: github.com/Nepherhotep/terevaka
Samples: github.com/Nepherhotep/terevaka-samples
UI Builder: github.com/Nepherhotep/terevaka-ui-builder
Official MOAI: github.com/moai/moai-dev
My fork: github.com/Nepherhotep/moai-dev
First of all, what tasks should the new framework perform?
First, the problems with the fragmentation of screens. And secondly (ta-dam), I wanted to have some kind of, even the simplest, graphical interface editor. Third, the framework had to define the architecture and file structure of the application as a whole. I want to say that the code turned out a bit (less than 600 lines), so even if the framework does not suit you, as it is, it will be easy to deal with its work and sharpen it for your needs.
Warning: the framework is sharpened under the landscape of the application, so if you need portrait mode, you will most likely have to spend some time on revision.
Let's go back to the fragmentation of the screens.
To solve the problem of fragmentation, the application needs to take into account:
- Different screen sizes
- Different permissions
- Different proportions
In order to solve all these three tasks in one fell swoop, Corona SDK or Gideros suggest choosing the scaling policy of the entire application. The most adequate of these modes is the so-called letterbox. This is when the application is uniformly scaled to fit the screen, but there are black bars along the edges in case of a mismatch of proportions.
In MOAI, as such, there is no mode, but there are snapshots of how to implement this in a few lines by manipulating the viewport parameters.
It is clear that such a half-measure cannot satisfy a really good application. The screens of mobile devices are already small, so that even their area is eaten by black stripes.
Obviously, we cannot do without an elastic layout (we solve the problem of dimensions / proportions).
As for the different screen resolutions, this is easily solved by a set of different graphics or its scaling. However, in Android / iOS, these mechanisms work in different ways, so you have to implement it yourself.
')
Sprite graphics editor
A graphical editor was written using PyQt. It is quite simple and can only manipulate sprites, I mean pictures.
MOAI supports text display, but neither the graphics editor nor Terevaka can display it. In practice, this means that if you need to apply text on top of the button, then you need to do it programmatically after the button sprite is loaded (or put the text directly on the button sprite, lol).
Nevertheless, the graphic editor is a powerful tool, since it allows not only to place elements graphically, but also to separate the view from the program logic.
The graphical editor stores the project file in a JSON file and exports the layer to the internal representation of Terevaka (Lua file) on the principle of one file - one layer.
Layers are of two types: elastic and scalable.
Elastic layer when displaying places elements depending on the sides of the binding. Those. If you want the element to follow the upper right corner when scaling, you need to specify the coordinates relative to this angle.
Example layer in editor:
Iphone 3.5 Inch:
Iphone 4 inch:
IPad:
A scalable layer is a different type of layer that scales proportionally, like letterbox. For example, the main menu makes sense to do it with the help of a scalable layer, but the background, however, is better done on the whole screen.
Example layer in editor:
Iphone 3.5 Inch:
Iphone 4 Inch:
IPad:
In the editor, the proportions of the scalable layer are fixed 427x320. These are the proportions of the iPad, reduced to the size of the iphone. You can choose more convenient parameters for yourself, but you need to remember about the resolution of the graphics that will be used in the designer and directly in the application. For myself, I use 853x640 (I need to change the parameter directly in the source code of the graphical editor) and upload retina to the editor. In the application itself, as a rule, I use even higher resolution textures so that the graphics match the large retina screens, and during the layer loading I specify the dpiMultiplier parameter so that the sprites load in the right size.
The reason why I use hard-coded 427x320 portions is that it's easy to get confused with sizes / resolutions, so who understands what's what, will figure out how to adapt it for your own case.
So, combining approaches, you can quickly create flexible graphics.
Files with layers are stored in the ./res/layout/ directory by analogy with Android.
Fragmentation of screen resolutions
Different screen resolutions are supported by a double set of graphics.
A set of graphics with the usual resolution is stored in ./res/drawable-mdpi/, and the retina is stored in ./res/drawable-xhdpi/. If the screen resolution does not match one of these, then the most suitable set will be taken and scaled. Directories ./res/drawable-ldpi and ./res/drawable-hdpi are not yet supported by the engine.
The important point is that when loading a layer, it is advisable to use packed sprites in one texture in order to optimize the amount of memory consumed. The framework supports MOAI format, which can convert paid TexturePacker.
Warning: do not use texture wrapping in TexturePacker with removal of empty areas, as there is a bug in the exporter in MOAI format and the graphics will eventually float.
miscellanea
To get a sprite from a layer, use the findPropById function (again, the analogy with Android)
To handle clicking on the sprite, it is enough to attach a special callback (see an example in terevaka-samples).
For other various usage examples, see the terevaka-samples project. To run the example, copy tereavaka to the example folder, or better yet, make a symlink into it.
To test the application under different screens, you do not need a lot of different devices at all - use launch profiles. The finished profiles are in the directory ./terevaka/profiles.
To run with a profile, use the moai ./terevaka/profiles/ipad.lua main.lua command, where ipad.lua is the ipad profile. The profile is usually 3-4 lines, you can easily create your own profiles.
Sprites for ui builder need to be saved in mdpi resolution.
Summary
Initially, the project began as the selection of some common code from the code of my new game. In an attempt to structure, both the code itself and its requirements led to the emergence of the framework, and then, using my old ideas, and the graphic designer to it. In addition, MOAI itself had to be refined, but thanks to the quick response of its developers, all changes have already been made to the main repository.
Also - this is a demonstrative experience that you should not be afraid to write your libraries, if you clearly understand the requirements for them, and also if you write in the scripting language :)
Links
Terevaka: github.com/Nepherhotep/terevaka
Samples: github.com/Nepherhotep/terevaka-samples
UI Builder: github.com/Nepherhotep/terevaka-ui-builder
Official MOAI: github.com/moai/moai-dev
My fork: github.com/Nepherhotep/moai-dev
Source: https://habr.com/ru/post/176771/
All Articles