|
by Jon Irons
Welcome to the JUICE utility. Our intention with JUICE is twofold:
While JUICE can already do many useful things, we have plans to continue expanding its capabilities. We will allow for editing more aspects of polygons (setting media and lights in particular), and will expand the utility to understand and manipulate the actual data for media and lights. We will also add support for platform editing. In addition, the programmers of JUICE intend to work with Aleph One and its developers to help enable entirely new features; for example, if colored lighting is ever implemented, JUICE will be the first editor capable of manipulating the new map data. So, while JUICE is a specialty tool, it will be the tool of choice for mappers who want to work with future features.
JUICE is, of course, written in Java, and is completely open-source. We want to help others interested in making editors by writing (mostly) clean source code that is also easily ported into other projects. The entire backend ought to be able to do this at some point in the future, and another editor can pick up in the areas where JUICE leaves off--for example, in creating map geometry.
The target userbase of JUICE is the network mapmaker group. As both Watts and I know from experience, netmappers have to deal with many tweaks in rapid succession: playtest, tell your playtest group to wait, make changes, rehost. Many of today's best netmappers do not use the Macintosh Operating system, and with the newer Intel Macs, the ``Classic'' MacOS (version 9) is no longer accessible directly from OS X. Instead, both groups have to use emulators, which always introduce some level of inconvenience; even if it were running at full speed and bug-free, an emulator usually has to find some way to transfer files to and from its host system.
JUICE runs on many systems, and does not require emulation. It can make map tweaks in a fraction of the time it takes to start up an emulator and go through the workflow (open Forge; adjust parameters, quit Forge, transfer from emulator; shut down emulator). JUICE is not just faster than this method in a general sense; working in it has some powerful functions that speed up tweaking considerably. Without going into too much detail, I can say that working with tables as JUICE does, in conjunction with keystrokes, produces results at incredible speed. Add sorting, and you can find entire groups of things and edit them.
While netmapping is our primary concern, JUICE works fine for other kinds of levels. Because it can operate on merged maps or even merged ``unimaps,'' it is invaluable for last-minute edits that would be a pain to do with the traditional Forge workflow. For example, if you forget to add the Co-operative play mode to a level, or if you forgot to change its name before merging, you can simply open JUICE and edit either parameter quickly.
In short, JUICE is a program by mappers, for mappers. We hope that you find it as useful as we do.
Running JUICE can be very easy to do. But first, you need to make sure you have Java 2 SE 5.0 installed (if your Java runtime is up-to-date, you should be fine). If you are on Mac OS X or Windows, there shouldn't be a problem. Linux users, on the other hand, may have more than a few things to deal with. It may be tempting to use the GNU Compiler Collection implementations, but in my experience, they either have many bugs that make using JUICE very inconvenient, or they don't run at all. You will need a "real" Java SDK from Sun (or, if you're on a PPC machine, find some way to install IBM's Blackdown SDK).
Once you are sure Java is installed correctly, running JUICE can be very simple. Go to the directory that was created when you unzipped the JUICE files, find JUICE.jar, and double-click it.
If you're a Linux user, again, things might be different, depending on your configuration. If you can't launch JAR files graphically, or if you're on any operating system and you want to view JUICE's output to stdout (what you might call a "prompt" or "terminal"), use a terminal to change to the JUICE directory and then run JUICE with the following command:
java -jar JUICE.jar
Either way, after a brief wait, you should see a screen like the one in figure 2.1.
From here, you can access some of the basic functions of JUICE.
Before you start delving into the program, you should set up a few preferences to make editing easier.
First, open the Edit and click the bottom option, Preferences (see figure 2.2). Take a moment to ogle the other options that will be available to you once you begin editing in earnest. Once you have the preferences menu open, you should see a window similar to the one in figure 2.3.
The most important and convenient preference is the top one: the default path to your map directory. Using this, you will set a starting point for JUICE when you decide to open or save a file; by default, it starts somewhere in your user directory (``My Documents'' on Windows, and your home directory on most other systems). Take a look at the example provided in my own preferences in figure 2.3.
If you're on Mac OS X, the path will be similar. On Windows, you might need a different approach. For example, if all your maps are in C:\Aleph One\maps\ then you would put that into the path field instead. If you do this successfully, you can save a lot of time you would spend navigating to the place where you usually put your files. Click OK to save the preferences and exit this menu. There will be a new JUICE Preferences file in the same folder as the JUICE.jar file you used to launch JUICE. If you want to keep these preferences, make sure you move them with JUICE.jar.
The other three preferences come into play when using the ``Auto fill'' feature that comes in handy when you edit monster or item parameters (see Subsection 4.3.5: Auto fill). The autofill feature will automatically fill up certain fields in these paramters, and you set your preferences here. For example, if you wanted to auto-fill your items' parameters so that the minimum number was 2 times greater than the initial number, you would enter 2 into the second field in figure 2.3 (called ``Minimum ... * initial''). To make the maximum number four times the initial number, you would enter 4 in the third box. Finally, to make the appearance rate 56%, for example, you would set the last field to 56.
JUICE can open a wider variety of map files than any utility or editor before it. Here's a list of what it can open:
To open a map file, go to the File menu (shown in figure 2.4) and choose Open. You will be presented with a file choosing dialog (2.5). Navigate to the location of the map file you want to edit. Then click "Open" and the map will load.
There is an alternative way to load a map for more experienced users. At the bottom of the main JUICE window is a text box with the text "Path to map file:" above it and a Load button next to it. If you know the path of a map file by heart and want to load it quickly, type it in here and press Load. This can be very useful on POSIX systems with hidden directories that the File Chooser won't be able to see. Check out my example in figure 2.6.
When loading maps--in particular, large maps--you might see JUICE appear to "freeze." JUICE is simply taking a little while to load the map file. If this happens, you can make sure that JUICE is not actually frozen by checking the very bottom of the screen. During saving and loading, you wil see a "Loading Bar" there. It should look something like this the picture in figure 2.7. The dark rectangle in the loading bar will slide back and forth while the map loads (or saves), so if you see it, just wait for a little while; it'll probably be done within a few seconds.
Note that, when you've opened a map file, the main JUICE window's title bar is set to the name of that file.
Saving map files is somewhat tricky. You must be careful when you save because you will overwrite the file you are currently working on. If you make a mistake, and you don't have a backup copy, you'll have to try to figure out what you did wrong and change it back in JUICE. Because of this, I highly recommend keeping a backup of your map files, unless you're working on some minor tweaks that can easily be changed back. JUICE can save in any of the formats it can read; for example, if you open a merged "unimap" file, you will be able to save a merged unimap file.
In order to save a file in this manner once you have loaded a map file, you need to go back to the File menu and click on Save (fig. 2.8). From here, JUICE will over-write the file you're working on without any further prompting. Depending on the map file size, you may see the loading bar described shown in figure 2.7.
Sometimes, you will want to save an extra copy of the map file under a different name. This is also possible in JUICE. Simply access the File menu and click "Save As..." (fig. 2.9). You will see the familiar File Chooser dialog. Change to a folder that you have permission to write to (let's say, your Desktop folder) and type in the name of the new file you want to save, as shown in figure 2.10.
After a brief time, your new file will be created. Note: if you use the Save As... option, JUICE will begin working on the newly saved file instead of the old file you were previously working on. The main window's title bar will reflect this change, and will display the name of the file you just saved to.
After you are finished with your editing, you will want to exit the program.
Quitting is the easiest thing of all to do. Simply choose File and then Exit (fig. 2.11). You may also quit by pressing the close button that most operating systems have at the top of their windows; most often, it has an X icon on it.
The main JUICE window (shown again in figure 3.1) is used not only as a starting point for all the menus available in the program, but in and of itself serves a function. It is for editing the majority of the mission and level information settings.
In addition, it contains a pull-down menu that allows you to select the level you wish to edit--selection is by the level select name (as you would see in Aleph One when selecting a level in a Gather Network Game dialog or by using the level select cheat).
As you can see from figure 3.1, these settings include the following:
You can perform an interesting trick using the game type flags, as shown later, in Chapter 8: JUICE Tricks. On a similar note, the ``Capture the Flag'' game type is not selectable because CTF is in fact the product of enabling both ``Every Man For Himself'' and ``Kill the Man with the Ball.'' Therefore, in order to enable CTF on a map, you must enable those two game types, and if you have both enabled, the map is selectable as a CTF map, even if you don't want it to be. We believe this has to do with Aleph One's implementation of CTF: the ``flag'' is actually the ball from Kill the Man with the Ball, and the only way for it to show up is to have that game type enabled.
The Item and Monster Parameters settings are in what is called the ``plac'' section of a level; ``plac'' is short for ``placement,'' so that is what I'm going to call both of these things together.
Placement settings are the ones that determine such crucial factors as:
These are the most straightforward settings in the placement section. The initial, minimum, and maximum values should be your primary means of causing things to respawn. The ``initial'' field should be obvious enough: it is how many of that thing are on a map at game start. Generally, this is equal to the number of objects of that type that you have added to a map--like Forge, JUICE adds to or takes away from this value when you add an object--but, if set to a number lower than the number of spawn points for that object, not all of the spawn points will be initially in use. Setting it to a greater number seems to have no effect.
Minimum and maximum are less obvious. In the case of monsters, it's easy: only that few or that many monsters of any type may be alive on the map at any given time. For items, however, it is different. This number is equal to the number of items that may exist at any place: it includes items on the map, and in players' inventories. So if you are playing a network game with eight players, and there is a maximum of 6 SPNKRs on the map, only 6 players can carry one at a time; until one of those carriers dies, no more SPNKRs will spawn. If you have a mimumim number greater than 0, the engine will respawn new instances of that item or monster every ten seconds.
For example, with a minimum of 16 shotguns in a four-player game, you may have eight total shotgun spawn points in the level. If each player picks up two shotguns at the same time as the rest of the players (meaning that eight shotguns are now in play), in ten seconds, eight more will spawn to fulfill the minimum requirement.
To add a little variety to games, you may adjust the random spawn properties of any placement entry. As the name implies, the ``Random Location'' checkbox will enable an item or monster to spawn in a random location.
This is simple enough. However, since Forge came out, one of the placement settings has been labeled incorrectly: the ``Number available'' field. Although the field was supposed to limit the total number of an item that could ever spawn on a map, it never seemed to have the desired effect. In looking through the Aleph One source code to understand the Placement section of a level, we found out that the ``Number Available'' field is actually some Bungie shorthand for ``Random Number Available,'' and we have labeled it as such in JUICE. This field will limit the total number of items or monsters that can spawn in a random location. Let's say you had this field set to 1 for a Major Juggernaut, and you check the ``Random Location'' checkbox for it. During the entire time that someone plays on the level, only one Major Juggernaut will spawn in a random location. The rest will spawn according to their spawn point objects. You can check the ``Infinite Available'' box to allow for unlimited random-placement spawns of a given object.
The final field in the placement settings is the Appearance Rate (or often called the ``Appearance % Field''). We are still unclear about the exact workings of this number; according to the source code, it only applies to the rate at which something may spawn in a random location; however, years of mapping show that it has an effect. We believe it boils down to this: if an item or a monster has a minimum value that is greater than 0, this field applies only to random spawn locations. However, if the minimum value is 0, it applies to non-random placement as well, which is why many powerups on modern network maps have a minimum of 0 with a rate that controls how quickly the power-up respawns. We will continue working to clear up this small mystery, but, as I said, experience shows that this description is more or less correct.
One of the departures of JUICE from Forge and most other editors is its interesting and useful commands. In almost all of JUICE's menus are special commands that can make mass-editing a lot easier. Figure 4.2 shows the commands available in JUICE's Item and Monster Parameters windows.
This, like most commands, is more or less self-explanatory. If you use any of the other commands in this menu, you may undo the last one. So, before you panic about setting everything to 0 via a command, relax, and try the Undo command.
If you use this command, it will reset all items' or monsters' values to 0 except the initial number. This is useful if you are, for example, converting a network map (which generally allows items to respawn) to a single-player map, in which mappers often try to limit the numbers of items.
This will reset all values to 0 (or, in the case of the Random Location flag, ``off''). This is handy if you're planning on completely re-doing the placement and spawn settings of items or monsters.
This will set all values in the selected row to 0. If you have removed all instances of an item or monster from a map, it's a quick way to clear its field to make sure it won't spawn at all.
This is the most interesting new feature in the Commands menu. Using autofill, you can fill all fields according to a formula you can set using preferences (see Section 2.2: Preferences). Note that this will not do anything to rows whose initial values are 0; however, anything with an initial value greater than or equal to 1 will be set up according to the settings you define via preferences.
Ah, yes. Polygons are the basis of all Marathon levels; without polygons, a level can't exist. Before you get too excited, remember that JUICE is not a graphical editor. You can't use it to adjust polygons' positions or to add or remove polygons. We have decided that such features are better left to other kinds of editors. Here's what you can edit in JUICE's polygon editor:
Notice in figure 5.1 that the polygon editing window is once again in table form; you can sort polygons by their editable fields (obviously, the most useful is sorting by type).
A polygon's type is easily edited, and chosen from a pull-down menu as seen in figure 5.1. As an experienced mapper, you should recognize most of the polygon types available in the main menu. However, some are new in the Aleph One engine, or were added in to support Marathon 1 maps (and the M1A1 scenario). I will describe these types to you.
For use in Capture the Flag levels. Honestly, I can't say how the original CTF mode implemented by Benad used them, but I do know how the newer CTF Lua script (presently at version 4) uses them. A base polygon will be the location of a team's flag (see section 5.2, Permutations, for more details).
Also known as ``Ouch'' polygons, these were present in Marathon 1, which did not have liquids. Therefore, in order to implement lava or goo, the game needed a kind of polygon that would deal damage. Minor damage polygons are analagous to lava, and Major damage are analagous to Pfhor goo. Note that any position within a damage polygon, be it on the floor or in the air, allows the player to take damage. You might use this to simulate a radioactive room, or to fool players in netmaps--why not make those water-covered polygons deal some damage, too?
In spite of the name, these polygons do not cause players or monsters in them to get stuck inside. Instead, the glue and superglue polygons act in conjunction with the glue trigger type, serving as a sort of modified monster trigger.
Editing a polygon's permutation is easy: just click in the number field and type the new permutation number. A simple definition of a polygon's permutation is the target of that polygon. Some polygon types' permutations are obvious, some are not, and some don't even have a use for the permutation field.
This type's permutation designates the light that is activated by entering the polygon.
The permutation of a platform on trigger polygon is the polygon index that the trigger will activate. Obviously, the target polygon should be a platform.
See Subsection 5.2.1.1.
See Subsection 5.2.1.2.
A teleporter's permutation is the index of the teleporter's destination polygon.
Goal permutations may range from 0-10. It's just the kind of goal that this is (if you don't know about goals, read the FORGE Manual).
The first kind of permutation for an automatic exit is the destination level that the automatic exit will lead to. For a novel second kind of permutation, see Chapter 8: JUICE Tricks.
A base polygon's permutation is the color of the team that owns the base. The colors are numbers ranging from 0-7:
What would go in the platform permutation? It turns out that there is another section of the level data that defines the platforms in a level. This permutation is the index of one of the platforms. You probably don't want to mess with this until we allow you to edit platform parameters; however, if you're curious, check out Chapter 8 to see some possible tricks that can go with editing this permutation.
The rest of the polygon types appear to have no reliance upon their permutations. We'll keep fiddling around to find out if this is true, but from what we've found so far, editing these poly types' permutations won't do anything.
Remember that thing I said in the introduction about adding totally new stuff to map files? This is one of those new things. You may add a comment to any level you wish; the maximum length is 512 characters (anything more will be truncated). For the moment, it is only used internally; Aleph One doesn't even read it.
So then, what is its use? Our intention for the level comment (or, as I like to call it, the ``JUCE'' Chunk) is for things like adding level author information; a small Readme for each level, to describe which engine version it requires, which Lua script, etc.; notes written to yourself or to other mappers--especially if you are taking turns in a Map Making Roulette, and wish to notify the next guy of any changes.
To our knowledge, editing a map and saving it in any program other than JUICE will eliminate any of its levels' comments. This may be inconvenient, but in certain situations, especially during an MMR, it's not so bad; it erases the previous mapper's comment and allows the present mapper to add a new one for the next guy.
There are two ways to add a level comment, by typing directly into the text field, and by importing a text file.
As seen in figure 6.1, there's not much to adding a new level comment. You just type it in and press OK to confirm or Cancel to erase the comment. Either button will also return you to the main JUICE window.
This method allows you to use a template or to edit and save level comments externally, in case you want to put them back in after you've used another program to edit.
The Commands menu contains the Read from file command. Choosing it will bring up the familiar file chooser window. Pick a file (hopefully a text file), press OK, and you will have the first 512 characters added to the level comment.
Here, we come to the heart of JUICE: editing objects. An object refers to any of the following things:
Take a look at figure 7.1, the Objects editing window. You will see the usual column arrangement; each is easily sorted by clicking the column title. You will also see the little Commands menu that appears in other sections.
Type and Subtype are both pull-down menus; which type you choose affects which subtypes are available.
Polygon, x, y, and z should make sense already. Entering a polygon that does not exist in the level will cause the field to set itself to the highest polygon index available. Z is not an absolute z-coordinate; as in Forge, it is the distance from the polygon's floor (or ceiling, if the ``from ceiling'' flag is checked).
Each type has some nuances associated with its parameters. Here are some explanations of each type's oddities.
Well, I lied. Monsters are monsters, and aren't too complicated. Maybe that's why it's the first type!
Scenery is also pretty straightforward. Just note that, like items below, scenery may have a facing value. And remember that only texture-set-specific scenery is loaded, so you can't choose a water puddle in a lava set map, etc.
In case you didn't know, items can have facing values, just like monsters and scenery. This only has an effect if you've modified the shapes file to contain multiple views. Also note that we allow you to use several unusual item subtypes--we allow all ball colors (the regular ball is apparently the ``red'' ball); Alien Weapon ammunition placement and ``knife'' item placement.
Player objects are mostly straightforward. The most interesting thing to note about them is that the player subtypes are all team colors, so you can use JUICE to create team spawn points for games like Capture the Flag and team King of the Hill.
Goals' subtypes range from 0-10, just like in Forge. If there is support for more than 11 goals in Aleph One (and it was simply a limit imposed by Forge), we will add more later. But who needs that many?
Thanks to some complications caused by the optimizations introduced by Forge's merge process, editing sounds is tricky. Therefore, if an object is not a sound, you can't change it to a sound; otherwise, all types are interchangeable. We intend to find some way to understand the merge process, or, if that fails, we'll simply strip the level of this information.
Sounds also have a confusing convention: their ``Facing'' value is actually the value of their volume, on a scale from 0-180. If the value is negative, this means that the sound's volume is tied to a light; the formula is v=-1*(l+1), where v is the value entered in the volume field, and l is the light's index. For example, if you want to link the volume to light index 20, you would enter -21 as the value for volume. We will make this process more intuitive when we add support for lights.
The commands for Objects are highly useful, and are streamlined from years of mapping experience. Figure 7.2 shows the list of commands.
As you can see, there are quite a few useful ones included in JUICE, and we're likely to add even more. Also notice that we have keyboard shortcuts for most of these essential commands.
Each of these does what you would expect: copy puts a copy of the object into memory; select another object and use paste to over-write it with the copied object; use duplicate to add a new object with the properties of the selected object.
The only information that copy does not copy is the polygon and x-y-z coordinates of the object. Duplicate, on the other hand, creates the new object with exactly the same parameters.
We added this command because JUICE does not have a graphical way of editing the coordinates of items. We didn't want to risk a player putting an item in impossible coordinates, so we give you the option of centering the object in its polygon. From there, you can change its position bit by bit until you're satisfied. Centering does not change the z coordinate; instead, z is set to 0, since that's where most objects are located anyway.
This should be obvious. Adding an object puts a new one at the end of the list; its initial type and subtype are ``scenery'' and the first subtype of scenery (level-dependent). It is automatically centered in polygon 0.
Removing an object is the reverse of adding one. I hope you knew that.
This will cause all objects in the level to be set at exactly floor height (or ceiling height, if they are hanging from the ceiling).
This will bring up a window with all of the flags available for a particular object type. Some flags are available for all types, while others are not. Goals have no flags. See figures 7.3-7.7.
This is probably the neatest command in all of JUICE. Use it to convert all objects of a certain subtype to a different subtype that part of the same type as the original. For a clearer explanation, see figure 7.8.
JUICE's approach to editing allows for a few very interesting tricks. We have decided to hide little or nothing from mappers, instead giving them access to many values as if they were editing the map file's raw hex code (but far safer, of course). I guess you could view these ``tricks'' as undocumented features; either way, they provide different or new ways of doing things.
Note: steps with chapter or section references are possible (or sometimes only possible) in JUICE.
Have you ever created a great secret that led to a secret level, but realized with a sinking feeling that Aleph One's level select cheat allows the player to enter that level at will? Well, if you are editing mission and level information (see Chapter 3), you can set a level's game types so that none are selected, not even single-player mode. This will hide the level from all level select lists.
Be careful with this feature. You should put all hidden levels after your visible levels, because if you hide a level, and levels after it will be offset in the wrong direction. For example, let's say you hid level 2 of a three-map netpack. If a player gathers a game and selects level 3 from the level list, he will actually select level 2. This problem appears to be remedied if you place hidden levels after normal ones.
I had started fiddling with editing a map's hex code and I saw that there were two locations that held a level's name. I didn't think much of it until I made a level that I thought should have two names: one for the level select dialogs (such as the level select cheat or the gather network game selections) and the overhead map screen.
I realized that it was possible when I remembered the extra name reference in a map file. Using the Edit Level Name menu (see Chapter X), you can set a level's two names to different values.
Something to note: the level select name comes into play in another context: on the metaserver. When a player hosts a game on the metaserver, it is the level select name that is printed and sent as a message to other players, telling them what is being hosted.
I admit, I picked this up from some map I don't remember. But I couldn't find any documentation on how it was accomplished, and so I took the time to find out for myself. Follow these steps to have a teleporter that only functions when a certain switch is ``on'':
If you remember from Subsection 5.2.2.2, it is possible to set a polygon's platform permutation. There are many interesting consequences of this that the automated systems in Forge and other editors did not allow. I'll use one example and let you think of others.
Let's say you want to make a ``platform on trigger'' polygon that monsters can trigger. This isn't normally possible. However, if you create a platform that is triggered by monsters (maybe a crusher or door, or whatever you want to trigger), you can do this exact thing.
This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir7041l7MH9b/lyx_tmpbuf0/index.tex
The translation was initiated by on 2007-03-12
