The Simarboreal-editor executables for windows, linux, and mac can be found
here.
This documentation is intended to allow any user to effectively use the Simarboreal editor, so all details of the software's user interface that can be discussed, will be discussed(While the target audience is developers, a fair few users use this tool for recreation or just to check it out). As such, some of the introductory discussion may be unnecessary for advanced users, and much of the descriptions will be described in plain english. The functions will be discussed in units split into chapters, which can be quickly accessed using the index titles and your browser's search function.
INDEX
1. Installation, setup, and basic controls
1.1 Running Simarboreal-editor
1.2 Launcher Interface
1.3 Keybinds and Controls
1.4 Saving, Loading, Exporting, and Tree Stats
2. Visualization Options
3. Tree Parameters
3.1 Tree
3.2 Branches and Roots
3.3 Leaves
3.4 LOD
3.5 Grid
4. Deep Alpha
4.1 Diagnostics
1. Installation, setup, and basic controls
This unit will discuss launching and configuration of the editor, as well as basic keyboard and navigation controls. If you're familiar with the isosurface demo's controls and setup, then this chapter will likely not be needed.
1.1 Installation
he executable files for Mac, linux, and windows can be found in jar files found in the release folder. Extract the contents of the jar file corresponding with your operating system.
1.2 Launcher Interface
The launcher is a simple interface with six display options, the start button, and a button that closes the launcher. The six display options are as follows:
I. Resolution Box: This dropdown box has settings like "320 x 240" and "640 x 480" and higher. If in windowed mode, the resolution will also determine the size of the editor's window, but will stretch to fit in fullscreen mode. This setting determines the size of the images rendered in the editor, in pixels.
II. Color Depth: There are two options, 24 bpp or 16 bpp. Bpp stands for "Bits Per Pixel". Essentially, more bits per pixel means more unique colors, at the cost of additional memory. Depending on your display and display settings, this setting may have no visible effect and may be best set to 16 bpp to conserve memory.
III. Refresh Rate: Depending on your display, you may have only one option (typically 60 hz), or additional, higher settings like 75 hz or 120 hz. Hz stands for hertz, or your refresh rate. This setting is only available in fullscreen mode. This setting has no effect on performance, but even if you get, say, 500 fps, you will always see at most the fps you set here.
IV. Anti-Aliasing: Improves the appearance of far-away objects. Anti-Aliasing works by rendering each frame at a higher resolution than normal and shrinking it down. Depending on the size of your tree(s), this may have no effect.
V. Fullscreen Checkbox: Checked = Fullscreen, Unchecked = Windowed. Checking this checkbox will reset your resolution to an extremely high setting and may change your color depth setting, so be sure to adjust your resolution after toggling this setting.
VI. Vsync Checkbox: Vsync fixes the brief stutters and tearing that occasionally occurs when turning quickly in-game. It does so by "reducing" the editor's fps to that of your display's refresh rate. This is a recommended setting.
1.3 Keybinds and Controls
This is a list of Simarboreal-editor's keybinds and their functions.
ESC - Freaking murders the instance.
SPACE - Toggles between editing and viewing mode. Editing mode frees your cursor up to use the UI, while viewing mode removes your cursor from the screen and allows you to move your camera around.
Mouse - Look around in viewing mode.
←/↑/→/↓ - Rotates the camera in its respective direction.
W/A/S/D - Allows for movement forward, left, backward, and right, respectively.
Q/Z - Allows for upward and downward movement of the camera, respectively.
F3 - Toggles the editing UI, coordinates, and data usage interface.
F5 - Toggles the rendering data in the bottom left.
Print Screen - Instantly saves a png of your screen, with an alpha channel. If the skybox is disabled, the sky will be transparent in the image.
1.4 Saving, Loading, Exporting, and Tree Stats
You can save your tree's parameters for long editing projects or to return to an ideal set of parameters by clicking the "Save parms" button. This will save your tree configuration, but that type of file cannot be used as a mesh. You can use the "load parms" button to open any Tree Parameters file, including parameters from other people, naturally. If you discover a very nice set of tree parameters, be sure to save and share it. ;)
The "Export j3o" button exports the tree as a j3o file. Due to how the leaves are rendered, trees can only be exported as j3o files until a suitable alternative is developed. There are currently no immediate plans to support exporting to other formats.
The "Save Tree Atlas" button produces two png files . They depict the tree in four iterations; one from each of the four cardinal directions. The first one is a color map, while the second one, suffixed with "-normals" is comprised of normal maps for the images.
Tree Stats, as in the triangle and vertice count can be found directly above the save, load, and export buttons. "Verts" represents the vertice count and "tris" represents the triangle count. Those are the only numbers you should be concerned about when considering whether you have room to increase the quality of the tree or not. The stats in the bottom right corner cover everything in the instance and will greatly inflate your number if you rely on them.
2. Visualization Options
The visualization settings are present in the topmost tab in the window. By clicking the "visualization Options" bar, you can minimize these options. These are options that don't affect the tree itself, but allows you to change its surroundings and how it's rendered in the editor.
Time of day (*) - Changes the position of the sun, changing the shadows and lighting accordingly. At 1 or 0, the most extreme values, the sun is right on the horizon, lighting is at its darkest, and shadows stretch on forever.
Shadow Strength (*) - The opacity of shadows. For drop shadows, it makes the gradient more visible as the value increases, while for normal shadows it renders the shadowed areas as pitch black at a volume of 1.
Grass - Toggles a grass texture on the neon green floor.
Sky - Toggles a light blue skybox. The sky is a static color that is unaffected by time of day. Screenshots taken using the Print Screen function will render the sky as an alpha channel when it's disabled.
Avatars - Toggles two grey character models for scaling purposes.
Wireframe - Toggles yellow lines on the edges of all triangles on the tree.
Test Pattern -Toggles a gridlike pattern on the tree instead of the bark texture.
Bump-map - Toggles rendering of the bumpmap in the trees bark texture.
Wind - Toggles a swaying animation for the tree, which is affected by a number of other settings.
Shadows - Casts single-opacity shadows from the sun to the tree.
Drop Shadows - Draws a radial black gradient under the tree. The size of the shadow as well as its center will adjust itself depending on the size of the tree and the center between all of the branches. The drop shadow will get smaller the higher the branches are, and is most opaque at a precise distance. If all of the branches are too near the ground, then the drop shadow may appear unusually faint or not appear at all.
3. Tree Parameters
These are the effectual items in the editor that create the changes the to mesh of the tree itself. They are separated into five tabs that focus on specific parts or elements of the tree.
3.1 Tree
Settings spanning different sections of the tree that wouldn't fit neatly into other sections.
Seed - Regenerates the tree using the chosen number as the seed. Randomly changes the appearance of the tree within the constraints of the other parameters.
Radius (m) - Scales the radius of all parts of the tree, in meters. The visible length of all branches are preserved, so the tree will grow up and outwards as the radius increases.
Height (m) - Adjusts trunk height, in meters, somewhat scaling branch length with it.
Root Height (m) - Adjusts the length of root segments. A larger root height value denotes a larger root system.
Y Offset (m) - Offsets the tree from the center point vertically, in meters.
Texture U Repeat - Adjusts the texture tile scaling to have more or less iterations. Lower values mean larger looking textures.
Texture V scale - Adjusts the vertical scaling of the tree texture. Smaller numbers will appear to stretch the texture vertically, while larger numbers will compress it.
Wind Flex Height (m): Adjusts a soft minimum height for wind flexing in the entire tree. Changes here are only visible with wind enabled.
Trunk Flex: Adjusts the amount of bending seen in the trunk due to wind flex. A value of zero will cause the trunk to no longer flex. Changes here are only visible with wind enabled.
Branch Flex:Adjusts the amount of bending seen in branches due to wind flex. A value of 0 will cause branches to no longer flex. Changes here are only visible with wind enabled.
3.2 Branches and Roots
The settings affecting tree structure below and above the trunk. These settings are split into 5 levels, ranging from level 0 to level 4. Level 0 affects the trunk and is used in conjunction with the inherit function (discussed later), while the proceeding four levels determine the traits of each level of the branches/roots, with the first level being the first branches splitting from the trunk, the second being the ones branching from those branches, and so on. The terms branches and roots are used interchangeably here, as they share the exact same parameters which function very similarly.
The checkboxes on the level 1-4 tabs toggle each branch level. Unchecking a branch level will remove all the subsequent levels as well (Disabling level 1 branches will disable level 2, 3, and 4 branches as well).
The following details this section's named parameters:
Inherit - Causes the level to inherit the settings from level 0. If inherit is checked for a level, any changes made to that level's parameters will not be visible until inherit is unchecked.
Radial segments - Determines the number of surfaces running along the length of the branches. The lowest setting makes the branches triangular, with the highest setting making them appear round. This has a significant effect on polygon count.
Length Segments - Determines the number of individual segments in a level. The minimum setting will make each level completely straight. Has a significant effect on polygon count.
Segment Variation (*) - Determines the variation in the contortion of the length segments. Higher values will make the length segments more variable in their contortions, while a lower setting will make the contortions less dramatic. The lowest setting creates a smooth curve along affected branch levels.
Taper (*) - Adjusts the tapering for a level. Low values will cause the level to taper more, while a taper of 1 will cause there to be no tapering at all.
Twist (rads) - Twists the branches/roots of the level, in radians. Twisting in one level is most visible in the subsequent levels, as it completely rotates them.
Gravity (*) - Adjusts the level's tendency to contort downward. A negative value will pull the level upward, while a positive value will pull the level downward. This setting does not alter the length of the level.
Side Joints - Determines the number of branching points in the level's nodes (Where it splits into the next level's branches/roots). For instance, a branch or root with a side joints setting of 5 will have five limbs branch from it at the next level. Naturally, this has no effect on the lowest level branches.
Angle (rads) - Adjusts the rotation of that level's node, in radians. This parameter will rotate subsequent levels.
Inclination (rads) - Adjusts the angle of a level's branches, relative to the parent node they're attached to. Increasing inclination causes branches to be more aligned with their node's orientation, while decreasing it causes their orientation to be increasingly dissimilar, until all of a level's branches form right angles with their nodes.
Radius Scale (*) - Scales the level's radius from the branches' node. This affects the radius of subsequent levels. At max, the radius of a level is 2x that of its parent nodes.
Length Scale (*) - Scales the level's length from the branches' node. This affects the length of subsequent levels. Depending on the height of the tree, maxxing this setting will make your tree pierce the heavens.
Tip Joint - toggles a joint that grows upwards atop the tip of the trunk. Used to create tall trees.
Tip rotation (rads) - Rotates the joints on each side joint of a tip joint. This doesn't affect side joints on normal branches or roots.
3.3 Leaves
The parameters relating to the leaf billboards that can be applied to the tips of branches. This is, naturally, the section with the most customization options and has many features requiring extensive technical knowledge.
Enabled - Turns on the leaves. Shocking, I know.
Size (m) - Adjusts the size of the leaf billboards, in meters. That's all there is to it.
3.4 LOD
Level Of Detail settings. It is separated into four identical subtabs, the "Highest" tab, and tabs labelled Level 1-3. The subtabs contain settings for the mesh that come into effect at certain distances from the tree; changing detail depending on the level range the camera is in. Each sub tab has two numbers at the bottom, the number of LOD verts and a triangles statistic separate from the master triangles statistic.
Distance (m) - Default value is 20. This parameter creates a non-inclusive ring around the tree where one will be able to see the tree in full detail. Slight adjustments to this setting are advised for larger trees, if derendering branches becomes a problem.
Branch Depth - Allows you to choose how many branch levels are rendered, where 1 will only display level 0 (aka the trunk) and 5 will display up to level 4 branches.
Root Depth - Allows you to choose how many root levels are rendered, where 1 will only display level 0 (aka the trunk) and 5 will display up to level 4 root joints.
Max Radial Segments - Sets an upper limit to how many radial polygons will be rendered. This applies to the entire tree rather than affecting branches and roots separately. Setting a maximum of three will make all branches appear triangular, while setting a max of 24 will leave the appearance unchanged from its current settings.
Mesh Type - This parameter has three options: Normal, Flat Poly, and Imposter. The normal type uses normal triangles and possesses the highest detail and graphics cost. The flat poly mesh type turns the branches into quads (think four sided branches) that rotate themselves to always face the camera. The imposter mesh type uses a copy of the tree's Tree Atlas to display a billboard of it that changes depending on the angle.
3.5 Grid
Settings involved with rendeing repeating or similar iterations of the same tree. These do not change the tree. Trees in the grid will take on different heights if the tree's Y offset is adjusted.
Width - Adjusts he number of tree columns, adding trees to the east.
Height - Adjusts the number of tree rows, adding trees to the north..
Spacing (m) - Adjusts the distance between trees in the grid.
Seed Range - Adjusts the number of seeds usable in the grid's trees. Larger seed range = more unique trees in the grid.
Rotation Variation (*) - Adjusts the maximum rotation for other trees in the grid
Lean Variation - Adjusts how far trees lean in a direction within a grid.
Scale Variation - Adjusts the range of possible scales for each tree.
Position variation - Adjusts the positions of trees in the grid so that they don't form a perfect grid.
4. Deep Alpha
This chapter is dedicated to diagnostic and technical features of the tool. Currently, this chapter is only for describing the diagnostics interface.
4.1 Diagnostics
In the top right are your coordinates, with your Memory and Data Memory usage below them. East is toward the positive X direction, west in the negative x direction, north is in thepositive Z direction, and south is in the negative z direction.
In the bottom left is a menu that can be disabled using the F5 keybind. Most notably, it displays your fps, but it also displays lots of basic rendering data. It should be noted for basic users that, although the menu in the bottom left lists "vertices" and "tris", those numbers do not represent the counts in the meshes themselves.