OrbEdit

From OrbEdit Wiki

Jump to: navigation, search

Contents

OrbEdit

OrbEdit is the level editor for the Orb engine. OrbEdit makes it easy to build levels for your game and write scripts for all your game Elements. If you're familiar with other Windows development environments, you should feel very much at home with OrbEdit. Read on to see what OrbEdit can do!


Terminology

First, some terminology to get us started.

  • Project - A collection of Levels, scripts, sounds, images, and other resources that make up your game. Each Project you create should be thought of as its own game. OrbEdit allows you to create new Projects and manage all the files within them.
  • Level - A single level of your game. A Level is simply a stack of one or more Layers, which could be anything from a single Layer for your simple puzzle game, to 12 different Layers for a complicated scrolling mountain range in the background of your awesome platformer. Levels are also referred to as maps, boards, or stages.
  • Layer - A wrapper for a WorldSpace within a Level. Layers can either be local or shared; local Layers are saved in the Level file, whereas shared Layers are saved in a separate file and referenced by the Level file. See Layers for more info.


File Types

The following is a list of file types which Orb uses, and the icons with which OrbEdit displays them. Many of these files can be executed directly within OrbEdit, either from the Project Explorer or QuickScript views. However, in general, they will be referenced by the Elements in your World as textures, event scripts, or sound effects.

Image:OrbGoldSmall.png .oprj: An Orb Project file, contains the name and version of the Project, as well as parameters used to deploy your project. Project files are in XML format. Each Project has exactly 1 .oprj file.

Image:OrbSilverSmall.png .olvl: An Orb Level file, contains all definitions for all Elements of all Layers which make up a Level. For shared Layers, a reference is made to the shared Layer file. Level files are in XML format. Each Level has exactly 1 .olvl file.

Image:OrbBronzeSmall.png .olay: An Orb Layer file, contains all definitions for all Elements of a single Layer, which is referenced from one or more .olvl files. Layer files are in XML format.

Image:Script.png .lua: A LUA script file, contains LUA commands which control Orb. Every game made with Orb is entirely driven by LUA scripts, see Scripting for more information.

Image:Import.png .oimp: An Orb Import file, contains the definitions for a collection of Elements which can be imported into a Layer. You can export your selection of Elements at any time into an .oimp file for later importing. Import files are in XML format.

Image:SpriteSmall.png .bmp, .jpg, .tga, .gif, .png: Image files, used to texture Sprites. Certain Shaders may use image files as well.

Image:Sound.png .midi, .wav, .ogg, .mp3: Sound files, used for sound effects and music within your game.

Image:Xml.png .xml: Plain XML files are used for a variety of purposes, including storing your QuickScripts, defining Registries, and describing what files to copy when you deploy your project.

Image:Text.png .txt, .cfg: Miscellaneous files used for configuration purposes, or anything else not directly used by your game.


Selections

Image:SelectedBody.png
Clicking on an Element within the Drawing Area creates a selection. Selected Elements are colored green and slowly pulse. The selection is the set of Elements to which actions happen. For example, when you click the Delete Image:Delete.png button, the currently-selected Elements will be deleted. The same applies for cutting, copying, and even pasting.

When you add a new Element to the World through the Add Menu, the new Element will be added as a child of the selected Elements. For example, if you select 3 Bodies and then select the Add Circle command, a Circle will be added to each of the 3 selected Bodies. Likewise, importing an Import File will attempt to import the new Elements to the current selection.

You can add and remove items from your current selection by holding down Ctrl as you click. In addition, there are various ways to alter your selection from the Select menu, such as inverting or clearing your selection. Likewise, you can control which Elements can be selected by dragging a selection box around them via the Image:MultiSelect.png button in the status bar. Being familiar with the all the selection techniques can save you a lot of time.


Anatomy of OrbEdit

OrbEdit is made up of a number of views which help your organize and build your game. Each view is its own window and can be docked onto any other view, or detached and placed anywhere you like. Whenever you start OrbEdit, your views will be automatically positioned the same way they were the last time you used them. Views can be opened from the View menu and closed with the Image:CloseX.png button. To move a view around, click and drag its title bar just like with any other window. You will be given cues as to where it can dock, or you can simply leave it floating.


OrbEdit


Below are detailed explanations of each OrbEdit view.


Drawing Area

Image:DrawingArea.png The Drawing Area represents the World, where your game happens and is the main window of OrbEdit. Here, you can select sets of Elements, drag them around, scale them, change their properties, and zoom in and out. All Layers in your project are displayed here at once, although new Elements can only be added to the Active Layer. The Drawing Area appears exactly as your final game will appear so it's easy to compose your level.

Right-clicking will bring up a context menu from which you can add new Elements, cut and paste, or delete. Several Element types have special features that can only be reached from this context menu, such as mirroring Shapes or resizing a Sprite to match its texture size.

The Drawing Area has several convenience shortcuts:

  • Holding down Shift while moving the mouse around will resize the selected objects, in the same way that the left mouse button moves objects. For Elements such as Line Segments or the sides of a Polygon, Shift will move its other endpoint so you can easily place it exactly where you need it to be.
  • Holding down Ctrl while rolling the mouse wheel will scroll the Drawing Area horizontally instead of vertically.
  • Several different types of files can be dropped on to the Drawing Area for different results:
    • .oprj: Closes the current project and loads the file as a new project, same as opening an .oprj file from the File->Open->Project Image:OrbGoldSmall.png command
    • .olvl: Closes the current Level and loads the file as a new Level, same as opening an .olvl file from the File->Open->Level Image:OrbSilverSmall.png command
    • .olay: Adds the file as a new shared Layer to the currently opened Level
    • Image File: Textures any selected Sprites with the image
    • Sound File: Plays the file as a sound

Additionally, the Drawing Area accepts keyboard input the same way your actual game will. Any keys you press while the Drawing Area has focus are routed through the Input Handler. When designing your input system, it is recommended you select keys that OrbEdit doesn't already use, otherwise you will be performing 2 actions with one keystroke - the OrbEdit action and the action for your game.



File Editor View

The File Editor View is OrbEdit's built in text editor. It has built-in syntax highlighting and bookmarking functionality for all supported Orb file types, as well as autocomplete and calltips for Lua scripts. You can execute scripts directly from the File Editor by clicking the Execute Image:Run.png button, or check your scripts and XML files for syntax errors with the Check Image:Check.png button.

The File Editor offers a handy way to insert code snippets, from Insert Snippet Image:Snippet.png option on the context menu (default shortcut Ctrl + J). Snippets allow you to quickly insert often-used bits of code whenever you need them.

You can define your own snippets in the /Core/OrbEdit/Config/Languages/lua.xml file, as well as add keywords, modify fonts and colors, and modify the editors keyboard shortcuts. See Hacking OrbEdit for more information.

To open a file in the File Editor, you can:

Autocomplete

As you type, the File Editor will occasionally pop up a list of items, known as an autocomplete list. This list is filled with known fields for the symbol you have just typed. For example, if you type orb., the '.' character triggers an autocomplete list, and you are shown all the functions and fields in the orb table. Any valid Lua indexing character can trigger an autocomplete list, that is, the '.', '[' and '["' characters. You can select an item from the autocomplete list by double-clicking it, pressing the tab key, or pressing another indexing character key.

Autocomplete lists can only currently be displayed for items defined at the global scope.

Calltips

Similar to autocomplete, when the File Editor recognizes that you are about to call a function, it will search through its list of known functions for documentation on that function. If found, it will pop up a small window with that documentation, including the function's signature, return values, and parameter descriptions. For example, if you type print(, a window will pop up with the documentation for the print() function.

Image:FileEditorView.png



Project Explorer View

Image:ProjectExplorerView.png The Project Explorer View offers you a tree-like view of all the files and directories in your game. You can freely move these files around by dragging and dropping them, as well as rename Image:Rename.png or delete Image:Delete.png them. If you make changes to your Project's directory structure or files outside of OrbEdit, you can refresh the Project Explorer with the Refresh Image:Refresh.png button. Additionally, all directories can be expanded or collapsed with the Expand/Collapse All Image:ToggleExpanded.png button.
Moving, renaming, or deleting a file from within the Project Explorer View will actually move, rename, or delete that file on your hard drive.

Certain types of files can also be executed from this view, using the Execute Image:Run.png button or by double-clicking them. Executing a file generally has the same effect as dragging that type of file onto the Drawing Area, as described above. This functionality makes it simple to test your scripts out or to automate certain tasks, just write a quick script and execute it from the Project Explorer View as many times as you'd like.

Many types of files can be directly edited with the Edit Image:Edit.png button. Editing will open the selected file in the File Editor View. This functionality is mainly designed for editing scripts, but it is also useful to be able to peek inside Levels and Imports from time to time.

You can also drag and drop any files or directories from the Project Explorer View onto the QuickScripts View. This makes it very easy to get your favorite scripts into the QuickScripts View so you can always find them when you need them.

The last important functionality the Project Explorer View offers is to let you change the startup script for your project. This can be achieved by right-clicking on a script file and selecting "Set as Startup Script". See the Deployment section for more information on startup scripts.



Layers View

This is the view through which you manage the Layers of your Level. At the minimum, you must always have a single Layer, but no more than 32 Layers. New Layers can be added via the New Layer Image:OrbBronzeSmall.png button. New Layers are local by default. To create a shared layer, simply right click on a Layer select "Shared Layer", and enter the name of the file you wish to save the Layer to. Layers have an additional "name" field which is only used to make it easier to identify what the Layer does, such as Background or Menu.
See the Layers section for a lot more information on how Layers work.

Layers can be re-ordered by using the Move Layer Up Image:Up.png and Move Layer Down Image:Down.png buttons, and can be cleared of all their Elements or removed from the Project entirely. Shared Layers can be loaded from file using the Load Layer from File Image:Load.png button. Clicking on a Layer will set that Layer active which colors it purple and causes its full list of properties to show up in the Properties View. The only way to change a Layer's Parallax and ZoomRatio properties (besides direct scripting) is through the Properties View.

The eye icon Image:EyeOpen.png and padlock icon Image:PadlockOpen.png are used for hiding and locking a Layer, respectively. By default, all Layers are visible and unlocked. If you wish to have a Layer be part of your Project but don't want it cluttering up your Drawing Area while you work, hide or lock it.

Image:LayersView.png



Properties View

Image:PropertiesView.png The Properties View allows you to view and change the properties of the currently selected Elements. Properties are listed in a categorized alphabetical order and are accompanied by a small description of what they do. If your Element selection contains more than one type of Element, only properties common between all types are displayed. This allows for the properties of multiple Elements to be changed at once. If no Elements are currently selected, the Properties View displays the properties for the WorldSpace of the Active Layer.

The Properties View does a moderate amount of validation on the values you enter. Invalid values for a certain property will write an error message to the Console and reset the property to its previous value. If a value is set to something other than its default, it will be displayed in bold. Once you have changed a property, that change will take effect as soon as you press Enter or click anywhere else in the application.

The Properties View is updated slightly less than real-time, that is, if you move your selection around with the mouse, its new position will not be reflected in the Properties View for several frames, depending on the size of the selection.



Console View

All messages from OrbEdit and from the Orb engine are directed to the Console View. Here you will be able to see color-coded output from your scripts as well as detailed startup information about Orb. The output from all print(), info(), warn(), and error() calls from your scripts will appear here.
The colors and font styles of the Console View can be changed by modifying the /Core/OrbEdit/Config/Languages/orbcon.xml file. See Hacking Orbedit for more information.

The Console View automatically parses URLs and filenames and makes them into clickable links. When a URL is clicked, your web browser will open and take you to the specified page. Clicking on a filename will load that file in the File Editor View and alternatively jump to a specified line number. For example: 

-- Print to the console
print("Scripts/Startup.lua:15");

will print a clickable filename, that when clicked, will automatically take you to line 15 of Scripts/Startup.lua.

Command Line

Below the output area is a command line from which you can execute Lua commands directly. A command is any string that can be executed as Lua, or the name of a Lua file to be loaded and executed. All entered commands are saved to the CommandHistory.txt file and can be retrieved by pressing the up/down arrows on the command line. Additionally, all commands are stored in the QuickScripts View as described below.

To enter a command, simply type the command on the command line and press Enter. To quickly clear the command line of all text, use the shortcut Ctrl + U.

Image:ConsoleView.png



QuickScripts View

Image:QuickScriptsView.png The QuickScripts View is a flexible container that gives you quick access to your most often-used files. You can add files and groups to the QuickScripts View by using the Add Image:Add.png button or by dragging items from the Project Explorer View.

Files and groups can be arranged in any order by dragging and dropping, or you can sort them alphabetically with the Sort Image:SortDown.png button. By default, QuickScripts comes loaded with a group for Scripts, Imports, and Commands, with a default set of handy script and import files. If you wish to modify the structure of the QuickScripts View directly, you can do so by editing your Project's QuickScripts.xml file.

The files and groups in the QuickScripts View do not necessarily reflect the organization of those files on your hard drive, thus, renaming or removing them does not alter the file on disk in any way. The QuickScripts View is meant as a convenient, secondary way to organize your data, so choose descriptive names for your QuickScripts that will remind you what they do.

OrbEdit tries to differentiate between Remove and Delete, in that removing something simply removes it from OrbEdit, whereas deleting something removes it from OrbEdit and deletes the associated data as well, for example, a file or Element.

Any commands that you execute from the command line will be added to the QuickScripts View under the Commands group, provided that a Commands group exists. This gives you an alternate way to quickly browse your command history and execute those commands again.

Some common uses of the QuickScripts View are:

  • Helper scripts to automate a process that must be done many times, such as arranging Elements in a specific pattern or texturing a common set of Sprites
  • A place to test scripts, such as when writing special effects. You can clear the active Layer, modify the script, and run it again as many times as you'd like without restarting OrbEdit.
  • Creating a collection of imports to make up a tileset. Any common doodad or tile for your game should be saved as an import so you can quickly add it to your level. It's a good idea to organize your imports by some criteria, such as "background doodads" or "snow level monsters".
Retrieved from "http://chalicegames.com/orb/wiki/index.php/OrbEdit"
Personal tools