====== Falcon 4 Cockpit Editor ======

[[https://www.pmctactical.org/forum/viewforum.php?f=47|Falcon 4.0 Forum]], [[:falcon4|Falcon 4 Home]], [[falcon4:campaign|Falcon 4 Campaign]], [[falcon4:cockpits|Falcon 4 Cockpits]], [[falcon4:database|Falcon 4 Database]], [[falcon4:file_formats|Falcon 4 File Formats]], [[falcon4:srtm|Falcon 4 SRTM Terrain]], [[falcon4:terrain|Falcon 4 Terrain]], [[falcon4:textures|Falcon 4 Textures]], [[falcon4:tools|Falcon 4 Tools]]

**Falcon 4 Cockpit Editor** by Seifer

====== Tutorial by Seifer ======

Some people asked me about how to use my editor, so I decided to write this small tutorial. This is not a tutorial on cockpit building, but instead, of the program itself. So one must be used to cockpit building to understand it fully.

====== Disclaimer ======

This program may be distributed under the terms of GPL.

This program is open source, which means, you can do whatever you want with the source code, except claim it as your own, and any code based on it must be also open source. For more information, see [[http://www.gnu.org/copyleft/gpl.html|GPL]].

And last, Im not responsible for any damage this tool may cause, use it at your own risk. I can assure you though that there is no code which is intentionally harmful to your machine.

You can also compile the source code youself using netbeans, and opening the project. The source is there, see it yourself =)

====== Requirements ======

You need java runtime enviroment. You can download it from [[http://java.sun.com
https://sdlc6a.sun.com/ECom/EComActionServlet;jsessionid=42FE242E4C25C9138D56AB34D3679EA7|here]].
Both java 1.4 or 1.5(or 5.0 as they say) machine work.

**With java installed, download the file from** [[http://homepages.dcc.ufmg.br/~mribeiro/falcon4/cockpitEditor-4.0.3b.tar.gz|here]], or additionally from [[https://www.pmctactical.org/f4/downloads.php|PMC Tactical Falcon 4 Downloads]].

The tar.gz file can be opened with winzip and other archiver tools, I guess winrar handles it well, and there was also a free one(powerzip i guess).

====== Running ======

Go to the folder you unzipped the program and look for a cockpitEditor.bat(or cockpitEditor.sh on unix systems). Execute it and the program main window will appear.

{{https://pmc.editing.wiki/images/CockpitEditor_mainWindow.jpg}}

In windows, a prompt window will also appear(a "DOS" window). Dont close it, java writes its output to this window. If you get memory problems, try adding the following to the java line in the cockpiteditor2.bat: -Xmx256M, this will increase memory pool java machine uses. So the line looks like:

<code>
java -Xmx256M -classpath build\classes cockpitEditor.cockpitEditorMain
</code>

//Note: If after the first time you open you get out of memory messages, restart the program, because java garbage collector is not to be trusted...//

The user preference button will show program options, like object colors, transparency settings etc. Right now, you CANNOT save those options. This will be implemented. They will work only for the current session.

Save and check buttons are only used when the pit is opened(more on that later). Clear button is just to clear message area.

To open a cockpit dat file, click the open button, and a browse window will popup. Choose the cockpit datafile(XX_ckpit.dat). If the auto res check box is selected, program will assume resolution from that XX name(8 means 800x600, 10 means 1024x768, 12 means 1280x960, 16 means 1600x1200 and so on). Otherwise, user will be prompted to enter the cockpit resolution.

====== Editing ======

This program uses a strong parser, which means the .dat file syntax has to be right. It wont accept wrong lines like falcons and codecs editor do. Why? Because its much easier to debug with a clean file. And its also more correct. So, its very common to find errors like missing comment entries (the double "/" lines without the double slash in the beginning). The program will point those errors though, and the line, so you can go there and check it youself. An example of a very common error:

<code>
Name: Panel 93600
Panel with a picture
// 0200 90 Ring
#93600 PANEL
        numsurfaces = 0;
        numobjects = 1;
        objects =  3601;
        numbuttonviews = 0;
        mousebounds = 0 0 935 1248;
        adjpanels = 93500 -1 93700 -1 92900 -1 93500 -1;
        offset = 0.0 0.0;
        pantilt = 49.0 -90.0;
        masktop = 1200;
        cursorid = 0;
#END
</code>

As you can see, all entries are correct. The problem is in the first 2 lines(the comments). Falcon uses C style comment (double /), and those first 2 lines are missing the double /. Program parser wont accept this kind of error, and will halt and point to the line. You can go there and add the double / at the beginning of the line. So the correction would be:

<code>
//Name: Panel 93600
//Panel with a picture
// 0200 90 Ring
#93600 PANEL
        numsurfaces = 0;
        numobjects = 1;
        objects =  3601;
        numbuttonviews = 0;
        mousebounds = 0 0 935 1248;
        adjpanels = 93500 -1 93700 -1 92900 -1 93500 -1;
        offset = 0.0 0.0;
        pantilt = 49.0 -90.0;
        masktop = 1200;
        cursorid = 0;
#END
</code>

It may take some moments while the program loads, and when it finishes, youll have 2 more windows, one for template and other for panels. The panel window also has a menu, with all panels, so you can access them directly.

{{https://pmc.editing.wiki/images/CockpitEditor_panelAndTemplate.jpg}}

Program will start in view 1100, as falcon does. To change to adjacent panels, use the numpad, as you would in falcon(if it doesnt work, press the NUMLOCK key). The panel you see is called the current panel. To view its properties, use shift P. To delete the current panel, use shift del. To create a new one, use shift insert.

**Creating a new Panel**

After you press shift + insert, program will ask you if you want to create a new panel. Say yes, and the panel properties window will show, all fields blank. You have to fill all values correctly, so this can be a bit hard. Lets walkthrough it:

{{https://pmc.editing.wiki/images/CockpitEditor_pp-main.jpg}}

//PanelID//: a number identifing the panel, must be unique among all panels. My program will probably be able to generate this automatically in the future, but that has some consequences(some users like to choose their own id, so Ill make this optional, but not right now). Some IDs are special. 1100 is the main ID, falcon uses it when you get in cockpit. There is also the co-pilot id(5100), the wide view id(**XXX**), the ghost mfd id(**XXX**). There is also the altpanel id, defined in the manager session by the altpanel = id; . I dont know how this altpanel gets called.

//Cursorid//: all cursors in the cockpit are represented by a number. So this points to the cursor you want. Use 0 if you dont want to change it.

//Dogeometry//: if you want to have the 3d cockpit model drawn in the 2d panel, check this. This is used to show wings, bombs, etc.

//Offset//: Wombat stated this only translate the panel surfaces. I thought it was used to adjust the HUD position, so the horizon is at the exact spot. Im not sure, as soon as I get my Windows box Im gonna test this. What I can confirm is that both values are integer.

//Pantilt//: tells falcon how is the pilot head when looking at this panel. I think the first number is the pan, and the second is the tilt, with negative values going up(left) and positive down(right).

//Masktop//: falcon uses this to save FPS. It basicallly means, if your panel covers some part of the window, do not draw the rest. So this is a number saying how much we shoud render in the 3d world. Xis tutorial tells never use a value of 0, so the program accepts anything in the range 1(panel covers everything) to Y resolution(render everything in the outside world).

{{https://pmc.editing.wiki/images/CockpitEditor_pp-buffer.jpg}}

//Buffer//: the background image. Use the browse button to choose one, or just write its name. Program will use a single surface, covering the entire panel(as per BMS2 optimizations). Surface editing is not possible, I dont know if ill get into that, because with BMS2 its not really useful anymore. If pit builders want it, Ill end up doing this.

If you leave buffer blank, program will consider a blank background.

{{https://pmc.editing.wiki/images/CockpitEditor_pp-adj.jpg}}

//Adjacent panels//: these are the adjacent panels of this panel. So when you use your hat switch up, you will go to the NORTH panel indicated here. So, fill all adjacent panels you want here, use -1(or the empty button) to mark it as a invalid link. This means the pilot wont be able to go into this direction.

So suppose you named this panel id 1200. You fill the NORTH value with 1100(main panel id). When the piltot uses his hat switch UP, he will go to panel 1100. In the 1100 panel, you must also fill SOUTH value with 1200, so the pilot can go back to the 1200 view using his hat switch DOWN.

A bit complicated? Well, thats how falcon works... If you leave it blank, program will use a -1 value(actually, any invalid value).

The goto button is used if you want to go to the panel in the field(click the goto), so it changes the current panel. The empty button mark that link as invalid(-1), so the pilot wont be able to go to that direction in game.

{{https://pmc.editing.wiki/images/CockpitEditor_pp-comments.jpg}}

//Comments//: all objects can have comments, which is a way of describing the object the way we want. Comments are lines beginning with double slash, C style comment ( double /). These lines are ignored by falcon, so they are there just to make the file easier to read by humans. You can write anything in this panel. IIRC, when I made this I checked to see if line started with double /, so you dont need to write them. But im not sure :-)

**Objects**

In the current panel, objects are outlined with different colors. If you click any one of them, youll have it selected. This is the current object. You can have multiple selected objects at the same time, if you hold ctrl and click other objects. With the current objects selected, you can do many operations:
- resize: hold control, and drag and drop the object. Program will choose the nearest corner as a base to resize the object. Resize can only be done in one selected object. If you got multiple selected, it wont work.\\
- move: hold shift, and drag and drop object. Program will move the selected area. You can also use arrows to move an area pixel by pixel.\\
- delete: delete key\\
- create a new object: insert key\\
- view properties: p key\\
- unselect current object: U key. This can be useful when you unintentionally click a light that occupies most of the screen.\\
- copy: ctrl C key. copies all selected objects to the clipboard. To paste, use ctrl V. Copied objects will have different ids from the source.

To create a new object, press the INSERT key. The following dialog will appear:

{{https://pmc.editing.wiki/images/CockpitEditor_ob-create.jpg}}

In the drop down, you can choose:


  * adi
  * buttonview
  * chevron/lift line
  * ded
  * dial
  * digits
  * hsi
  * indicator
  * kneeboard
  * light
  * machasi
  * text

Select the object type you want and click next. The new object dialog will appear(each object has its own dialog). For example, after selecting a buttonview and hitting next, you get this dialog:

{{https://pmc.editing.wiki/images/CockpitEditor_ob-dialog.jpg}}

The first tab is the main tab. As you can see, the id is automatically chosen for you. The editor gets the panel id and looks for an ID number close to it. In this case, panel is 1100, and object id is 1101. Program will only pick unused ids, so dont worry about it.

All fields should be filled correctly, else the editor will refuse to create the new buttonview. The parent button property asks for the id of the parent button. Each buttonview is associated with a button. So suppose the AA nav button is in panel 1100, 100 and 110. Actually, these are 3 buttonviews of the same button, or the same parent. A list of buttons can be found in the beginning of the file, after the sounds. Later versions of this program will let you pick the parent from a list.

The persistant property is used when you save a cockpit in game(**using alt+s IIRC, can someone confirm this?**). So if you want this buttonview to be saved in game, check this.

{{https://pmc.editing.wiki/images/CockpitEditor_ob-areas.jpg}}

The areas tab exists in all properties. Each object has destlocs and some also have srclocs. Desltlocs are the destination of the object, or where it will be draw. Buttonviews have only 1, but digits can have more(others too, you have to see it yourself). The 2 radio buttons beside the area are the transparent and opaque values. Buttons are TRANSPARENT by default, some objects are OPAQUE by default. So if you want something different from this, check the radio. Buttonviews with 0 states must be opaque to be seen by the mouseover. This is something that gave me lots of headaches to discover. Thanks for Badger for the help in this one.

If the button has states, fill the states and enter the srclocs. Each state is a position of the button(ILS button for example, has 4 states IIRC). So for each state, you must fill a source area in the template(srcloc), from where falcon will get the graphics for it. srcloc0 is ignored.

The "equal areas" make all srclocs the same size of the destloc. Useful for fine tunning buttons, and avoiding some graphics stretching. Some objects have this too, use mouse over too see a better description of buttons of this type.

The comment tab is the same of the panel, so I wont go into it again.

**Buttons**

Buttons are also referred as parent buttons. In game, all buttons and knobs you see are called buttonviews. All buttonviews refer to a parent button, which tells what the buttonview does. So you can have 3 different views for the same button, say ICP 0 button, one for each front view you have, for example. They all do the same function. I dont know why they did the same with lights, but that is beyond this scope.

To view the list of buttons for the cockpit, press B on the keyboard. The following dialog will appear:

{{https://pmc.editing.wiki/images/CockpitEditor_buttons-dialog.jpg}}

Each line is a button, with its ID, its callbackslot, and its label(see using labels). You have the following options:

  * new: allows you to create a new button, much like creating an object.
  * create bv: this button creates a child buttonview for the selected button. The new buttonview will be at location 0 0 100 100 at both panel and template. The number of states will be set to the button number of states.
  * view: opens a dialog with all the button properties, so you can edit them.(this should be called edit, not view)
  * delete: deletes the selected button from the cockpit. Warning: doing this, all buttonviews using this button will point to an invalid button. Use with caution, and only if you know what youre doing.
  * close: close the dialog.

the buttons dialog shows this properties:

{{https://pmc.editing.wiki/images/CockpitEditor_buttons-properties.jpg}}

The ID is the button ID. You need this for buttonviews parent buttons entry. States is the number of states the button has, ie: each position the button can be at.

Delay, according to Xis tutorial, can be either -1 or 0. A -1 value means the button goes back to the ealier position after you push it, like a telephone number. A 0 value means it holds its position after you click it. Cursorid tells the mouse look when over this button. Initstate tells the position the button will be when player enters the cockpit. Callbackslot tells what is this button function. A list can be found at: http://members.cox.net/cbodiker/buttons.html.

the sounds tab is not useful yet. It tells what sound the button will make when clicked. Its not working yet because Im not sure how it works.

The comments tab is for comments on the button.

**Using object labels**

One thing which can come in handy sometimes is the show label function. It works showing the object label over its drawing. Its activated using the L key. So, what is a label anyway? A label is a string, or a sequence of characters, in the objects comment, starting with the prefix "name:". You are free to use any label on the object. So suppose you create a button, and want to name it ANYNAME. So, what you must do is the following.

  * Click the object and hit P(properties);
  * Go to the comments tab;
  * Create a comment line like Name: ANYNAME
  * Push update button.
  * Done

The following images show how it works.\\
1) Object selected

{{ https://pmc.editing.wiki/images/CockpitEditor_labels-select.jpg }}

2) Comment tab

{{ https://pmc.editing.wiki/images/CockpitEditor_label-name.jpg }}

3) Result

{{ https://pmc.editing.wiki/images/CockpitEditor_label-afterok.jpg }}

====== Saving ======

After you created all objects and panels, save the pit:\\
- save: s key. Program will create a backup file. If your pit is called 16_bla.dat, backup will be 16_bla.bak. BEWARE IF YOU SAVE TWICE, BACKUP WILL BE LOST. So after saving, ALWAYS see if pit works in falcon. Else, restore backup. YOUVE BEEN WARNED. When saving, program will check for wrong entries and correct them(like manager entries). One less thing to worry about when building you pit =)

NEW If you use Shift S instead of S, a clean save will be made, which means non used objects will be removed. This can be useful for debugging dat file by hand, and sometimes it fixes some cockpits too.

If save fails for some reason, as some people are experiencing, try to see if a file with suffix .new was created. This is the temporary file program uses for the save. You can rename it (to, say 16_ckpit.dat) and use normally. This bug is being investigated, it happens only on some windows machines, dont know why.

====== Copy/Paste ======

Since version 2.13, a new copy (CTRL-C)/paste (CTRL-V) was implemented. It uses system clipboard to transfer data. This means you can copy paste objects from different cockpits. In fact, you can copy a buttonview in the editor, open notead and paste, and youll probably see something like (this is a buttoview from aeyes pit):

<code>
#1 BUTTONVIEW
    states = 2;
    srcloc = 2103 195 2159 256;
    srcloc = 2100 195 2156 256;
    parentbutton = 1011;
    destloc = opaque 1098 597 1154 658;
    persistant = 0;
#end
</code>

Similarly, if you take the test above from a text editor, copy and paste to the editor, the program will read it, parse on the fly and add to you cockpit. Cool, isnt it :-)

Right now, falcon objects only can be copied, so MFDs, RWR and HUDs cant(these are panel properties). Cant have it all, I guess...

====== Hints ======

Sometimes, clicking an object to change its state can move it. So I added a key to change state. Select the object and press T to go to next state and shift T to go to previous one. Control T resets the object to original state. Last, Control Shift T returns all panel objects to original state.

Some people are reporting they are getting a blank screen with java apps. Well, Im not sure the reason, but looks like its video driver issues. Try disabling FSAA or updating drivers and see if it works.

Zoom: program has zoom for a while, but was missing here. It can be accessed using the + and - keys (on the keyboard or numpad).

Many people use a program to edit the panel and template images at the same time they edit the dat with this tool. If you change the images, you dont need to exist the program, just press the SHIFT+R combination and image will be reloaded. Do the same in template to reload it.

When creating objects, dont be too worried about srclocs and destlocs. What i usually do is create the object at 0 0 100 100 coordinates and move/resize it to the right place using the mouse.

You will be required to enter a callback slot when creating new objects. This is what the instrument actually does. A list of callbackslots can be found [[http://members.cox.net/cbodiker/buttons.html|here]].

For buttonviews, youll need to know the parent button number. Open a .dat file and see the list of buttons in the beginning of the file, after manager and sounds. This version has a list button, with the list of parent button for you to choose.

When creating similar views, use the copy paste feature, saves a lot of time. And also move the objects together. Different views can be made in a few minutes with this.

It is very useful to have a decent text editor, like editplus (I use vi).

If the prompt window outputs something like nullpointer exception, you probably found a bug in the program. Try to duplicate it and send me a mail, Ill see what can be done. My mail can be found in the doc folder, inside a file called thanks.txt, where I also thank people who helped me in this. Im always updating the link, so always check the latest downloads, cause your bug may be fixed already.

There is a small howto.txt file inside the doc folder, with the basic instructions. And the changelog for the curious, showing the latest changes.

Also, I very much welcome suggestions like: hey, you could do a button to make areas equal, or something make user life easier.

And if you find this tool sucks, feel free to say too. Negative feedback is important, so I can improve it. Enough said, you are on your own now!

I really hope you enjoy this tool as much as I did implementing it. And its still going, of course =) I try to squash bugs as much as they come, so plz feel free to contact me about them.

Have fun\\
Seifer out

Source ([[https://www.pmctactical.org/forum/viewtopic.php?t=20842|PMC Tactical Forum]]).

====== Tutorial 2 ======

To create a new cockpit, press the "New" button, select the resolution and directory for cockpit. An empty cockpit will be created. Go to the template window and hit shift P. Load background image and have fun.

====== KeyMap ======

**NUMPAD**: panel walk, switch views.\\
**ARROWS**: fine tunning, move current object 1pix around

**C**: check pit\\
**S**: save pit\\
**A**: toggle alpha channel(transparency) for rectangles. Slow!\\
**N**: toggle night view(was render needle, use dial property now...)\\
**O**: show the panel object list, and user can select them from there.\\
**B**: show cockpit button list, user can delete, create, edit existing ones.\\
**P**: show selected object properties, with shift show current panel properties.\\
In template, allows changing the background image.\\
**U**: unselect the currently selected objects\\
**L**: toggle labels on, right now I use the comment on the object, a line with a name:. I get everything after the :. This is cool! With labels on, in the template you can identify each area, as they are labeled as src0, src1, src2...\\
**E**: make srclocs the same size as destlocs\\
**T**: change selected objects state. Shift T for previous one. Ctrl T to reset.\\
Shift + I: auto align hud.
**I**: autocompute minpos and maxpos for indicators.

**INSERT/DELETE**: create/delete object. ADIs, Buttonviews, DEDs, Dials, Digits, HSI, lights, machASI can be created.

**SHIFT + DEL**: delete current panel.\\
**SHIFT + INSERT**: create new panel.

**SHIFT + A**: selects all objects from current panel\\
**CTRL + C**: copies selected objects from the current panel to the "clipboard".\\
**CTRL + SHIFT + C**: copies all objects from current panel to clipboard\\
**CTRL + V**: paste clipboard to the current panel.

**SHIFT + B**: send the selected objects to background in the panel(will be draw in the bottom of the panel), useful for stacking objects, and reordering them.\\
**SHIFT + F**: send the selected objects to the foreground(will be draw on top of others)

**SHIFT + R**: reloads current panel/template background image(depends on the window you do it)\\
**SHIFT + I**: computes tilt value based on guncross position.

**+/-**: zoom in / zoom out\\
Users of international keyboard: if it does not work, try the numpad + and -

**R**: select RWR on the panel, or create a new one if its not present in the current panel.\\
**H**: same as above, but for hud\\
**1,2,3,4** on keyboard(not numpad): same as above, but for MFD left, right, 3rd and 4th

====== Colors ======

**Blue**: buttonviews\\
**Red**: lights\\
**Green**: panel objects(MFDs, HUD, RWR)\\
**Yellow**: objects\\
**Orange**: current selected object

====== Mouse ======

Click an object to make it selected. Also change states on buttons and lights. Ctrl click allows you to select multiple objects, move them, and copy paste them. Cool!\\
When selected, drag to move, drag the border to resize.\\
**ctrl + drag**: resize\\
**shift + drag**: move\\
**ctrl + click**: toggle selected for an object\\
Right button drag and drop: move all destinations(or source if in template) at the same time

====== Conf.txt ======

Use this file to write the path to your cockpits, so the program will open that directory when you click the open button.

example:
c:\games\falcon4