masterq32 / versatile

A simple 3D model editor based on simple quads and a sprite set.

VersaTile 3D Model Editor

VersaTile is a simple 3D model editor that allows editing models based on tilesets.

Tiles can be placed on an axis-aligned plane and a model can be constructed this way.

Features

• Model editing
• Undo/redo
• Vertex displacement
• Post-placement edit (move/rotate/mirror/displace/…)
• Export via Assimp

Usage

The editor is mainly controlled with the mouse. On the right hand side is a side bar that shows the models sprite sheet and allows the selection of sprites.

The center of the editor contains a 3D viewport that shows the model and allows editing.

Creating a model

When creating a new model, the following dialog appears:

It provides several options that must be set up correctly to import a sprite sheet:

• File Name This option is required and defines the file that should be used as the sprite sheet.
• Sprite Size This option defines the size of the smallest tile that can be selected in the sprite sheet view. This also defines the grid size.
• Spritesheet Margin If the sprite sheet image has a border around the contained sprites, set this value to the number of pixels this border is wide.
• Sprite Padding If there is a padding between the single sprites in the sheet, set this value to the number of pixels this padding is wide.
• Preview Here you can see a preview of the imported sprites. The magenta lines will disappear in the editor, but are displayed here for you to check if your setup of the sprite sheet is correct.

Navigating in the Viewport

VersaTile uses a grid aligned movement for the camera focus. This grid is shown as white lines and aligns itself to fit a comfortable insertion position.

To rotate the camera, hold the right mouse button and drag. Horizontal movement rotates the camera around the focus point, vertical movement looks up and down.

To move the focus point, press W,A,S,D,Q and E. W moves the camera forward horizontally, S moves it backwards. A moves to the left and B to the right. E moves the camera upwards and Q downwards.

For a quick rotation of the camera, all shortcuts listed in the table below.

If the option Automatic adjust grid orientation is set, the displayed grid will align with the camera so always the most convenient grid is active. If this option is disabled, the active grid can be changed by pressing G or the Toggle Grid Plane button.

Inserting a tile

To insert a tile, select the sprite on the right side by clicking and dragging until the wanted portion is selected. Now a tile can be inserted in the 3D viewport on the white grid.

When inserting, the tile snaps to the grid unless the Shift key is pressed, then a pixel perfect insertion can be done.

When a good position is chosen, a left click will insert the tile at the previewed position. Then, another tile can be inserted. To insert a different tile, just select another sprite in the right panel. To end tile insertion, press Space or use the Selection mode button in the toolbar.

Modifying an existing tile

Tiles can be modified in different ways:

Translate / Move

Click and drag the tiles center gizmo to move the tile on its own placement plane. You can move the tile up,down,left and right.

Rotate Left / Right

Click the corresponding button in the toolbar or menu to rotate the tile around its upper left corner.

Flip Horizontal / Vertical

Click the corresponding button in the toolbar or menu to mirror the contents of the tile.

Displace Vertex

This feature allows you to displace a vertex to the tiles own plane. Click and drag a vertex gizmo to displace it along the tiles normal.

This can be used to achieve slopes and skewed tiles.

Delete

Click the button on the toolbar or press Delete to remove the tile from the model.

Controls

Key	Function
W,A,S,D	Move camera focus horizontal
Q,E	Move camera focus up/down
Space	Cancel/Stop tile insertion
H	Flip horizontal
V	Flip vertical
R,Ctrl+R	Rotate tile
Shift	Enable fine grid snapping (pixel perfect)
Num-2	Rotate camera down 90°
Num-8	Rotate camera up 90°
Num-4	Rotate camera left 90°
Num-6	Rotate camera right 90°
Num-Plus	Zoom camera in
Num-Minus	Zoom camera out
Right Mouse	Drag to rotate camera
Left Mouse	Click to select, modify or insert tile
Delete	Remove the selected tile
Ctrl+Z	Undo the last modification
Ctrl+Y	Redo the last undone modification
Ctrl+H	Rotate camera into Home position
Ctrl+T	Rotate camera into Top position
Ctrl+F	Rotate camera into Front position
Ctrl+G	Rotate camera into Side position
Ctrl+Shift+H	Set camera home position
G	When AutoGrid is disabled, selects the next grid option
F	Moves the camera center to the currently selected tile.

Supported Export Formats

VersaTile supports exporting the created 3D models with Assimp. Every format that can be exported by Assimp can also be used with VersaTile.

On export, the Y-axis is up and the model is scaled in a way that a single texture pixel is equivalent to one model unit.

So a model that is 64 pixels wide is also 64 units wide.

Preferences

In this dialog, you can set up your preferences on how VeraTile should behave.

Behaviour

Automatic adjust grid orientation

When this option is active, the grid will align itself with the camera as soon as it is moved.

Horizontal Grid Threshold

This is a factor from 0.0…1.0 that scales the y axis when determining the current auto grid.

The lower this is, the later the grid will align into "horizontal" mode, allowing more camera movement before swapping into horizontal mode.

Display

Ground Display

Determines the way a ground plane is shown. When None, no ground plane is visible, Grid is a static horizontal grid, even when the vertical one is shown and Solid is a solid, green surface that is supposed to resemble a grassy ground.

Ground Size

The extends of the ground in tiles. The larger this is, the larger the ground will be displayed.

Show Coordinate Axis

If this option is enabled, the coordinate axis are shown by three short lines in the colors red (x-axis), green (y-axis) and blue (z-axis). The intersection of the three lines is the current camera focus point.

Credits

Thanks for each Crocotile3D and Sprytile for inspiring me to create VersaTile!

Also thanks to kenney.nl for delivering our default tile set! It suits this editor very much.

More Screenshots

versatile's Issues

Add "drag'n'put"

When placing tiles in grid-aligned mode, add an option to do the following:

1. Position a tile with the cursor
2. Press left mouse button
3. Drag to another position
4. Release mouse button
   VersaTile should then place a tile on each grid cell that was dragged over. Kinda like pixel painting

Another example texture

The example texture draws a connection to Crocotile3D which is there (obviously) but having a unique default texture would help the project to distinguish itself like Sprytile does. Maybe we find something with a free license (like CC0 or similar) which can be used for a good example model.

Add action to recenter camera on currently selected tile

Title says it all:
A hotkey/button that sets the focus pointer to the center of the current tile

Snapping to grid (from topview)

It seems that there is an offset from the mouse position, when I try to place a tile from top view. I moved camera/grid upwards, and there was like one tile offset, it might be a bug?

Sprite translation along normal

A edit mode where a sprite can be moved along its normal instead of modifying all four corner points

Add option dialog

Add an option dialog to improve user experience

Rendering artefacts on ground tiles

when looking from top. See attached screenshot.

This might be a Z-Order/Buffer problem?

$ glxinfo | grep 'version'
server glx version string: 1.4
client glx version string: 1.4
GLX version: 1.4
OpenGL core profile version string: 4.5.0 NVIDIA 375.66
OpenGL core profile shading language version string: 4.50 NVIDIA
OpenGL version string: 4.5.0 NVIDIA 375.66
OpenGL shading language version string: 4.50 NVIDIA
OpenGL ES profile version string: OpenGL ES 3.2 NVIDIA 375.66
OpenGL ES profile shading language version string: OpenGL ES GLSL ES 3.20
    GL_EXT_shader_implicit_conversions, GL_EXT_shader_integer_mix, 

Close with unsaved changes

Feature request: Warning dialog when closing with unsaved changes to the model.

Cannot build because of hardcoded paths in project

When I open the project in QtCreator it can't compile because of hard coded paths:

Cannot read /home/felix/projects/gl3w/gl3w.pri: No such file or directory

I am using

• Ubuntu 16.04.2 LTS 64-bit
• Qt Creator 3.5.1
• libassimp-dev/xenial 3.2~dfsg-3 amd64

Fix export

The export right now is unbearably broken, although Assimp is used.

Proposal:
Remove Assimp, write own OBJ exporter with correct texture export

Save dialog does not work as expected

Current master version.
Repro:

• Create new model
• Click Save...
• Select save location
• Enter filename testname
• Click Save...
• Click Open
• Locate save location
  --> No file to open.

I assume it's because of the missing file extension.

1. Adding extension if missing
2. Allow opening any file with any extension?

Did you think about a license yet?

How about GPLv3?

Change the way tilesets with margin/padding are handled

Right now, VersaTile modifies the source texture on import. This may be unwanted behaviour if the user wants to rely on the original texture' setup.

Change it so the user can choose between a modified texture and a raw handling.

pro for unmodified:

• Easier handling when models share the texture
• May be easier for the artist

pro for modified:

• User can spawn tiles larger than a single sprite, even when the source material has padding and margin
• A bit easier handling in texture mapping

Builds for Linux

Could you make binary builds for Linux?

Maybe you could setup Travis Ci for autobuild .AppImage package?

Scrollable tile sheet

Feature Request:
Allow scrolling of the tile sheet when using very wide or tall tile sheets so all tiles are reachable.

Segfault on texture load

64bit Linux.

VersaTile works fine with default tileset.

When a new image is selected as a new texture (either by creating a new file or by attempting to switch textures on an existing one), the following error pops up in console:

...
"FS SIMD8 shader: 107 inst, 0 loops, 350 cycles, 0:0 spills:fills, Promoted 1 constants, compacted 1712 to 1152 bytes."
"FS SIMD16 shader: 110 inst, 0 loops, 532 cycles, 0:0 spills:fills, Promoted 1 constants, compacted 1760 to 1200 bytes."
QPainter::begin: Cannot paint on an image with the QImage::Format_Indexed8 format
QPainter::setCompositionMode: Painter not active
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
QColor::setRgb: RGB parameters out of range
...

and the preview is completely black (with horizontal grid lines visible on black). When I click to confirm loading, program segfaults.

This has been tested with both an indexed .png and a .bmp, with identical result.

Gizmo mouse hotspot isn't the same as the displayed one

When trying to click on a blue gizmo square, the gizmo may be recognized off by some pixels.

Improve tileset options

When creating a new model, add a preprocessing step for the tilesets to remove any margins and tile paddings from the sprite sheet, so more sprite sheets can be used.

Maybe also add an option for "previewing" the imported tile set with a grid on import.

Add UI button to reset insert mode and go into edit mode

title says it all

Make option for autoflipping grid

Change the grid behaviour so it is possible to either have

1. Auto-flipping (like it is implemented right now)
2. Manual flipping via a hotkey

Also add an option for setting the horizontal grid threshold

Custom Sprite Sheet Files

Allow the creation of custom sprite sheet files that store

• the image
• the minimal tile size
• a preselection of tiles
• predefined sprite groups

OpenGL problems

I have OpenGL 3.3 on Arch Linux, and I get this log when running it:

Change mesh, set mesh as clean.
libGL error: No matching fbConfigs or visuals found
libGL error: failed to load driver: swrast
Unrecognized OpenGL version
Unrecognized OpenGL version

"Edge Flip" Gizmo

An "edge flip" could be implemented so when an edge of a sprite is clicked, the sprite will rotate "backwards" around the opposite edge:

Fix camera movement

With the fix of #4, the camera movement broke.

Move position of vertices along plane of sprite, and UV coordinates

Currently single vertices can be moved orthogonally to their sprite but not in the other two directions. This would be a tremendously useful feature. My particular interest is in morphing tile-based meshes to make them slightly more organic.

In addition, the possibility to move the UV coords of single vertices with a similar interface would also be great. Could be used for avoiding texture stretching on slanted tiles for example, or for special effects (i.e. "truncating" a sprite).

It seems natural also that if these features are implemented they should really be paired with the possibility to flip the triangulation on a sprite.

Adds customizable controls

Title says it all

Add option to update texture

Add an menu item to update the models currently used texture.

Add option to show coordianate axis and camera focus

Title says it all, display it with RGB→XYZ

Grouping

Allow grouping of tiles into a single, translate-only package. Those packages can be copy & pasted as a single object.

Open wiki

How about opening the wiki so we can collect snippets and How-Tos like how to build?

Cannot select tile

I current build from master

• Ubuntu 16.04.2 LTS 64-bit
• Qt Creator 4.3.1
• Qt 5.9.1 64bit GCC

The tile in the red rectangle cannot be selected only larger groups around it.

Sprite Group Library

Allow the user to save sprite groups into a library that can be associated with the model file or the sprite sheet

Copy & Paste for single tiles

Implement a copy&paste option for a single tile.

Proposal:
Middle-Clicking a tile will select it in the tileset view and switches into insert mode. This allows fast duplication with a low overhead

Nomenclature: Sprite vs. Tile

Just for my under standing:

When it's 2D and in the right window then it's a sprite.
When it's 3D as part of a model then it's a tile.

Or the other way round?

Improve Ground Display

Always show a slightly visible ground grid and make an option to enable/disable the solid ground