BETA DOCUMENTATION

[NLB - comments beginning with NLB indicate beta-specific notes by Nathan Lamont]

# Introduction

The game Ares started as a smaller, simpler game. It's inner workings were not originally meant to be generally accessible. It had a somewhat organic development, and at times ugly things were done.

Hera does much to hide the ugliness. There are still aspects to editing Ares scenarios that are less pleasant than they could be, but Hera is a very powerful tool.

While you don't need to be a programmer to use Hera, you do need to be patient and technically inclined. ResEdit experience is strongly recommended.

# Basics

Hera creates single files which Ares can read. Ares can only read Hera-created files when it's first starting up. When Ares is not running, you can tell it to use a Hera-created file by dragging and dropping the file onto Ares, or by double-clicking the Hera-created file in the finder.

Any data in the Hera-created scenario file supercedes data which is duplicated in Ares' standard data files. For instance, if you have to a snd resource in the Hera-created scenario file with the same ID as a snd resource in the Ares Sounds file, Ares will use the sound in the Hera-created file if it is open.

Hera will never hurt the original Ares data -- any changes you make will be put your custom scenario files. Even if you edit text data that is used by Ares' factory scenarios, it will not be saved in the factory scenario files. The changes will be saved in your scenario's copy of data that's been changed.

The only Ares data which Hera can't edit are the interfaces -- the placement of the buttons on the menu screens.

## Data Types

In Ares there are seven unique types of data: scenarios, base objects, actions, conditions, initial objects, briefing points, and sprites.

There are also four additional types of data used by Ares that are standard MacOS resources: TEXT, STR#, PICT, and snd. Hera allows you to directly edit TEXT and STR# resources. As of this writing, you need to use a program like ResEdit to import your own PICT and snd resources into your custom scenario files.

### Scenario

In Hera, a scenario refers to the description of a level, or chapter. A scenario tells Ares what ships start out where, which player is which, and all the basic information that makes a level different from other levels.

When the player selects a level to play, Ares uses the scenario data to determine what objects, sprites, pictures, and sounds will be needed to play the level. It loads everything required (except the text of any messages), places the initial objects where they belong, and begins the game.

### Base Object

Base Objects are so named because they describe how the Ares engine should represent an object -- on what a real object should be based.

There are three types of base objects: self-animating sprites, rotating sprites, and devices.

#### Self-Animating Sprite

A self-animating sprite is any object which doesn't determine its appearance by the direction it is facing. Asteroids, for example, are self-animating sprites.

#### Rotating Sprite

A rotating sprite is any object which uses its direction to determine its appearance. Most ships are rotating sprites.

#### Devices

A device is a non-physical object. It has no sprite associated with it. Devices are special-purpose base objects used to describe other base objects' weapon behavior. For example, the cruiser base object refers to the photokinetic beam cannon object.

### Actions

Actions are what make things happen in Ares. Any time a weapon fires, or a missle hits a ship, or a transport approaches a planet, actions get executed.

Actions are organized into sequences. A sequence always gets executed from begining to end.

Actions can be invoked in two ways: by objects, or by scenario conditions.

### Conditions

Conditions are simple rules that get continuously evaluated while a level is being played. While a condition is active, it gets considered every few seconds. When it is found to be true, a sequence of actions is executed.

For example, a condition might be that if a certain planet is occupied by a certain player, then that player wins.

# Getting Started

The simplest way to get started with Hera is to use the "factory" scenarios as a source. Here's how:

After you've launched Hera, you'll be presented with the Main Window for the factory data. Click on the "Edit Scenarios" button. The Scenario Editor will open. Select "While the Iron Is Hot" in the scenario list (for now, don't choose any of the networking levels, "Between a Rock and a Rock," "Location, Location, Location," "Space Warz," "Scratching Post," or "Capture the Flagpod." . Select Copy from the Edit menu.

Close the Scenario Editor by clicking OK or Cancel. Select New... from the File menu.

Choose a location and a name for the new Ares Scenario file from the standard file saving dialog box. A new, empty scenario file will be created.

A new Main Window for the scenario you just created will be opened. Click on the "Edit Scenarios" button.

When the Scenario Editor opens, click on the empty scenario list on the left. Then select Paste from the Edit menu.

Presto! You have just copied the scenario. Not only that, you've also copied all the base object, action, briefing point, initial object, and condition data too.

Close the Scenario Editor by clicking OK. [NLB - currently you can only save from the Main Window, I think.] Choose Save from the File menu [NLB - Save As does not work yet] and then quit.

You can now drag and drop the scenario file you created onto the Ares application, and play the scenario you just created.

# Main Window

Title

This is how the title will appear within Ares itself. [NLB - where? Main screen for drag and drop, net setup screen?]

Version

If you distribute more than one version of a scenario under the same name, make sure you give it a new version number. This allows Ares to compare version numbers of the same scenarios when starting net games to make sure they are actually the same. [NLB - not yet]

This version number has no relationship with the version number used by the MacOS Finder.

Author

Your name as it will appear in Ares.

Author's URL

Your website, if you choose.

Download URL

This is where someone would go to get this version of the scenario file. You can use http://www.AmbrosiaSW.com/games/ares/addons.html as a default. [NLB - in net set up screen, if you don't have a scenario that the other person wants to use, you'll automatically get the url; a default url will be here]

# Scenario Editor

## Scenario Data

Number of Players

The total number of players, including computer players, in the level. Generally, this should be two, either one human player and one computer player, or two human net players.

While up to four players is technically supported, it has not been tested. Having a third computer player in net games is known to cause synchronization problems.

Fixed Angle

Usually you should keep this unchecked. It was implemented for the training scenarios. Checking this and entering a value creates the level at the same orientation every time.

When this is not checked, the level may be created at any angle, which is normal behavior.

Training Only

Checking this skips the mission briefing, and allows the player to simply bypass the level.

Chapter Name

Enter the chapter name. Chapter names normally have two lines, each beginning with \i. The first \i tells Ares to invert the first line, the second tells it to un-invert the second line.

Single player chapter names usually look like this: ``

\i Chapter 1
\i The Phantom Menace

There's a space after each of the \i's.

Net chapter names usually look like this: ``

\i Two Carbon Units Enter, One Carbon Unit Leaves
\i

Note that there's still a space after the second \i, even though there's nothing else on the line. Otherwise, the second line will still be inverted.

Edit Scenario Initial Objects...

Opens the Initial Object Editor for this level.

Edit Scenario Briefing...

Opens the Briefing Point Editor for this level.

Edit Scenario Conditions...

Opens the Condition Editor for this level.
Set Starmap Location...

Opens the Starmap Locator.

This allows you to set the postion indicated on the starmap presented at the beginning of every scenario briefing.

The starmap picture is stored in PICT resouce 8000.

Movie

Specifies that a movie should be played before the level begins. If a level has a movie, it is played before both any prologue text and the mission briefing.

A movie is specified by its file path in the Ares folder (the folder which contains the Ares application).

A movie called "Space Chase.mov" in a folder called "Space Attack" in the Ares folder would be specified by:

`:Space Attack:Space Chase.mov`

Checking the Movie checkbox or clicking the Choose Movie... button will open the STR# Editor to STR# resource 4500, where the movie path names are stored. You can add, edit, or delete movie path names.

Par Ratio

This value is not used.

Par Kills

This value, and all the par values, are displayed to a player when he completes a level. They should be reasonable values.

The values are used to calculate the player score.

The par kills are the number of ships the player should aim to destroy.

Par Losses

A player gets more points if he loses fewer ships than allowed in the par losses.

Par Time

This value is the time, in seconds, it should take an experienced player to complete the level.

Prologue Text

The prologue text is text which is presented in a vertical scroll before a the mission briefing, and after the level movie. It should be used to advance the story.

For net scenarios, the prologue text is used to describe the level in the net setup screen. It should be short.

Click the Prologue Text checkbox or the Choose Prologue Text... button to open the TEXT editor and choose and edit the text.

Prologue text (for single player levels) and epilogue text have special formatting characters.

Every paragraph needs to start with the characters `#+` on a line by themselves.

Optionally, the first paragraph can start with `#+B` (B for background) followed by the PICT resource ID of a background picture. So, for instance, if you wanted to use PICT resource 2005 as your background picture, the first few lines in your prolgue text would look like this:

`#+B2005
The mysterious blob is getting bigger. If you don't stop it soon it will take over the galaxy. This is your last chance.`

Any paragraph can also begin with just `#+` (no B) followed by the ID of a PICT resource. The PICT indicated will just be displayed above the paragraph it precedes. Such a paragraph might look like this:

`#+10016
This is a picture of the space blob. That little dot inside of it is the planet Grimpi. You need to destroy it right away.`

You can also use the sequence `\i` to turn on and off inverse text. To show a line of inverse text, you should have something like this:

`#+
\i The Tale of the Space Blob
\i`

Note that there's a space after the `\i` on both lines.

Epligue Text

Identical to the prologue text, except it is shown after the mission debriefing (where the player's score is displayed).

Status Strings

The Status Strings are a specially formated STR# resource which tells Ares how to display the mission status screen on the ship's computer.

Each indexed string in the STR# resource you choose is used to make a line on the status screen. The first string is used for the first line, the second string for the second line, and so on, up to six lines.

The strings must be formatted in a certain way. Any string may begin with _ (the underscore character) to indicate that that line should have a separator line in the ship's computer status display.

If the first character (or the first character after a _) is a - (a minus sign) then the rest of the string will be displayed as is in the status display. For example, the string `_-Kill the Blob` would appear as `Kill the Blob` in the status display.

If the first character (or the first character after a _) is not a -, then the string has a special meaning and must be fomatted like this:

`type\number\player\negativevalue\falsestring\truestring\basestring\poststring`

where:

- type = a number between -1 and 5, indicating:

  -1 | kNoStatusData | no status for this line
  0 | kPlainTextStatus |
  1 | kTrueFalseCondition | 0 = F, 1 = T, use condition not score
  2 | kIntegerValue | interpret score as integer (no decimal point)
  3 | kSmallFixedValue | interpret score as float (decimal point)
  4 | kIntegerMinusValue | value - designated score
  5 | kSmallFixedMinusValue | small fixed - designated score

- number = which score/condition #
- player = which player score (if any); -1 = you, -2 = first not you ( 0 if you're player 1, 1 if you're player 0)
- negativeValue = value to use for kIntegerMinusValue or kSmallFixedMinusValue
- falsestring = string to use if false
- truestring = string to use if true
- basestring = first part of string

For example, the string

`1\0\\0\0\N\Y\SHIP DESTROYED:`

would result in a status line based on condition 0; if condition 0 were false, the line would read

`SHIP DESTROYED: N`

and if condition 0 were true,

`SHIP DESTROYED: Y`

Another example: the string

`2\1\0\10\\\Samples Left:`

would result in the status line "Samples Left: " + score 1 of player 0. So if player 0's score 1 was 3, the line would read:

`Samples Left: 7`

## Player Settings

Click on the pop up menu to select which player number to edit. [NLB - these player numbers are 1-based (first player is player 1) but players are elsewhere referenced by 0-based indexed (first player is player 0)]

Player TypeA player may be either a single human, a net human, or a computer.

For single player games, player 1 should always be a single human. Player 2, if any, should be a computer player.

For net games, both player 1 and player 2 should be net humans. Ares uses these settings to determine if a given level is networkable.

Edit "No Ships" Text...

When a human player has no ships left, Ares must end the scenario whether or not other conditions have been met. You can edit the text which is displayed (if any) when the scenario ends under these conditions.

Race

The race pop-up menu determines the race of the player (the race names can be edited with the Race Editor). The player's race is used when ships are build by bases

# Initial Object Editor

# Briefing Point Editor

# Condition Editor

# Base Object Editor

attribute flag name | function
can turn | object has a direction it faces
can be engaged | hostile objects which can engage will engage this object
has direction goal | should be on if "can turn" flag is on
is remote | do not use
is human controlled | do not use
is beam | a vector object (as opposed to a sprite object)
does bounce | if it hits the edge of the universe, will bounce (ships should bounce, shots should not)
is self animated | sprite object who's sprite doesn't depend on the angle it's facing
is player ship | do not use
can be destination | can be selected as a target object
can engage | can engage other ships
can evade | can sense if another ship is engaging it and attempt to avoid being hit
can accept messages | do not use
can accept build | object is a base capable of building ships
can accept destination | can receive orders to go places by human or computer player
auto target | for weapons and the missiles they create; objects are created facing the nearest target; both the weapon and the missiles they create must have this attribute set for it to work
animation cycle | object's animation cycles (otherwise, object expires when animation ends)
can collide | object can collide with an obejct with the "can be hit" attribute set
can be hit | object can be on the receiving end of a collision
is destination | for non-mobile objects like stations and planets; must be set for objects that can be built; computer AI considers destinations places that should be attacked or guarded
hide effect | causes nearby thinking objects long range symbols to be masked
release energy on death | the object's energy will be released in the form of energy blobs when it is destroyed
hated | objects that are hated will be shot at by objects which belong to different players
occupies space | any object which should not occupy the same space as another; any thinking, colliding object should have this flag set
static destination | object's destination cannot be changed (should only set for specific initial objects)
can be evaded | ships with the "can evade" attribute set will try to evade this object if needed
neutral death | instead of dying when destroyed, object simply becomes neutral (as in the case of bunker stations)
is guided | doesn't think, can't accept orders, but still can steer itself and try to hit targets and still evokes evasion
appear on radar | shows up on radar
bit 31 | do not use
on auto pilot | used for human player; do not set

# Action Editor

# Sprite Selector

# Sprite Importer

# TEXT Editor

# STR# Editor

#