[GUIDE]Annoted template: desc (I warned you)

Zacha Pedro

Annoted template:
The dësc resource

Note: the dësc resource is so incredibly simple that this will also be the template for the other annoted templates, it will introduce the format and notations used in the other templates. Therefore, it should be read first.
Notice that these annoted templates do not aim at replacing the Bible, as I would just be repeating information found there, so you will need to read the Bible at times. However, the essential functionalities are explained, as are some things that the Bible does not explain as it's not its aim, but we thought you ought to know.
As always, I'll refer to the fields by the name they are being given in the Bible, since covering all editors would be too lengthy. You should be able to match them with the fields in your editor. Also, the annoted template will always make much more sense if you read it along with a known resource of this type.
The asterixes ( * ) indicate fields or flags (or even sometimes entire resources) that can be safely ignored at first, as not needed to make a normal use of the resource. They denote advanced features that are best viewed later. Just skip to the "put x to ignore" part or enter -1 if there is none.

The dësc resource is quite straightforward. It stores the descriptions that can be too long for other places to hold (STR# strings are limited to 255 chars), each dësc resource being one description. Originally (in EV) it just contained that, the text, technically a null-terminated text string, that can be any length you wish while taking only as much space as the text needs. In Nova there is some more data inside this resource, but all directly associated to the description.

The Description field
This free-length text field holds the actual description itself. There is no known technical limitation to the length of the description. However, there might be not enough room in the place the description will be displayed in the game for it to be shown in totality. At some points if the description is too long it will scroll, but consider the player may give up before reading the totality of the text if the description is too long! Also, a much shorter description is expected for the quick briefing (the text that appears in the mission info dialog) than for the planets or missions descriptions. Technically, all characters from the Macintosh extended ASCII character set can be used, though EVNEW will not be able to display nor enter them all if you're on a PC (but it displays and allows you to enter the ones that also exist in the Windows extended ASCII character set, that is almost all of them).
This text field is parsed (i.e. the engine search and replaces the indicated wildcards when displaying it by some info that may not be known at write time) with some wildcards, that are described at the end of the mïsn section of the Nova Bible (as most pertain to missions, such as the deadline or destination, though not all of them). You can see examples of this in most random-destination mission descriptions.
Also, descriptions can change depending on mission bits: with the syntax {bxxx "first text, to be displayed if bxxx is set" "second text, to be displayed if bxxx is NOT set"}, you can make the actual text depend on the state of mission bits; notice the second string is optional. bxxx can be replaced by G for descriptions that depend on the player gender. P can be used as well, but that's of no interest whatsoever for plug-ins, since the game must be registered for one to use plugs. It's possible to negate any of those three with "!", put before, but you could as well change the order of the strings. However, neither the other operators from the test expressions (such as Oxxx, Exxx), nor logical operators can be used there. Neither will the following work:
{b1 "{b2 "b1 and b2 are set" "b1 is set but b2 isn't"}" "b1 isn't set"}
Examples of use of {} descritions mutators can be found in the descriptions of most outfits (that can be found at IDs 3000 and up), with b424 being the bit telling that, being enslaved as part of the Vell-Os storyline, you can't buy most outfits.

The Graphic field
This is a number field (a signed 16-bit integer one, technically, as are all number fields unless otherwise noted; this means that values are constrained to between -32768 and 32767 (bounds included) in all number fields unless otherwise noted, and you can't enter decimals in any number field) that holds the ID of the PICT graphic resource to be shown along with the description if it supports it. Supported descriptions are all the windowed mission descriptions (i.e. not the mission offer text if it's offered from the mission computer nor the quick briefing text), in that case the image should be 200×200 in size and it will be put to the right of the description (this is used in the bounty hunting missions, for instance), the bar description, in that case the image should be 260×120 and it will appear above the bar desc (there's no use of the latter in the default Nova scenario); if the description will serve for a ship description, it references the ID of the image that will be shown along with the ship characteristics in the ship info dialog, that should have a dimension of 600×400 (don't neglect it, it allows your graphic guy(s) to show off his skills as the pictures he produces otherwise don't allow him such freedom).
If you don't wish any graphic or if the description doesn't support it, put -1 in here, -1 is the default "ignore this field" value, you'll find it often when browsing the data files.

The MovieFile field
This 31-char text string field holds the name of the QuickTime movie file to play before the description is shown (for mission descriptions obviously); the file has to be in the Plugin or Nova Files folder. Notice that it's one of the few cases the engine won't use a resource but an external file (the other being the intro music). The only use of this in the default scenario is in the four race fields that are at the reserved IDs 32760-63. You should make sure the movie is in a format that can be read by everyone's QuickTime version. Also, this is the only way to display a movie in the game. By the way, you shouldn't make a movie larger than 800×600, the minimum screen size Nova will play in, as some people are playing at this resolution. Leave blank if you don't wish any movie to be displayed.
The Flags field
Note: In the Bible and ResEdit with templates (the editor the Bible assumes), this is an hexadecimal field, but for you it's probably a number of checkboxes. In the future, I'll always refer collectively to these checkboxes as one field, the field of checkboxes, and describe them one by one.
These are some options for the display of the movie. They are ignored, obviously, if there is no movie (i.e. you leave "MovieFile" blank); there will often be fields that are ignored due to the fact they don't mean anything due to the value in another. It should be obvious and it won't be explicitely indicated in the future, you should be able to deduce they are ignored. As "ignored" says, you can put anything, the engine won't care, but for you to clearly see these fields are ignored you should put 0 or -1.
(HTML <ul> list)
- "played afterwards" makes the movie be played after the briefing (i.e. the actual description) instead of before; it may make more sense depending on the movie and the description.
- "double size" makes the movie be shown at double size if set, it may be worthwhile if the movie is a bit long, in that case you can render it at a small size (such as 320×240) and have the engine double the size for it to span a nice 640×480, so that the movie does not take too many megabytes in your plug distribution while playing in a nice part of the screen. Be reminded the author is the founding member, president, and so far only member of MUAAUMDS (Modem Users Association Against the Use of Movies in Downloadable Software), you should keep movies in your plug to a minimum, or if they are too big, allow people to download a movie-free version of your plug.
- "cinematic" makes the movie be considered a cinematic movie if set, that plays on a black background with fades before and after. You may not have the skills of the Blizzard cinematics team, but you can have your movies be played with a nearly as good evironment; this is most useful after a hard and important mission, usually the last one, as a treat for the player.

Only the second one is being used in he default Nova scenario.

There are some things of interest in the dësc section of the Bible, such as a list of reserved dësc IDs, that are hard-linked to a resource (i.e. mission ID 128 uses dësc ID 4000 for the initial briefing and no other, contrary to the other mission texts that have their ID indicated in the mïsn resource) or completely reserved. Also, some more technical details on mutable descriptions are available there, and check the end of the mïsn section for the list of wildcards and their meaning.

The name of the dësc resource has no interest whatsoever for the engine, so you can use it to keep track of your descriptions. You can use dësc IDs 128 to 32767. There is no known limit to the number of descriptions there can be (except of course running out of IDs, which makes 32767-128+1=32640 dëscs max), though it's advised to keep them to a maximum of around 500 per file, see how they are split between multiple files in the Nova data files.

What d'ya think of it? BTW, this will indeed set the template for the other annoted templates, and it would be better for the other people proposing annoted templates to observe this template as well. To sum up:
-first comes the "Annoted template:" indicator, to remind or confirm the guy is reading an annoted template if he just opens it
-then "The %%%% resource", just like in the Bible
-then a short description of the purpose of the resource, what it contains, and what it doesn't, if it isn't clear (for instance neither spïn nor shän contain the actual image data, they just reference it)
-if the name of the resource means anything or is in use anywhere in the game, its purpose should be put like the fields of the resource, just before all fields. If the name of the resource has no use, the fact it has no use should be put at the end, just like I did.
-then comes the list of fields, in the order they are in the Bible (though see exception below). It should be a <dl> HTML definition list, with the name of the field in <dt> and the explanation in <dd>. In the explanation of each field, first there should be the kind of field (number, text, but also checkboxes or popup menu if it's likely to be in that form) as well as the basic limitation (the length of the text that can be put in here, for instance). Then, maybe in the same sentence, should be what should be put in the field (ID of another resource, value from a limited list, amount of shielding you want to see in the ship info dialog, times 10), except if checkbox field: in that case, should come an <ul> list of the checkboxes, not attempting to assume any order as ther might be none in the editor (i.e. don't write "the first checkbox stands for, the second for, ... the last for"), and in each entry of this list what is done when each flag is set/checkbox is checked, and what it does if the checkbox isn't checked if it isn't obvious. Then, a longer explanation (that is clearly not needed anywhere here), some tricks, caveats, technical info, features, known issues, examples of use in the game or warning that there is none (either of the previous two is strongly advised, and mandatory for non-*'ed stuff that's not used in all other resources of the same type), etc, can be put afterwards in each field or checkbox description. At the end, what should be put for the field to be ignored, if applicable. Notice an asterisk should be put before each field that can be safely ignored at first, as not necessary for a basic behavior. Basic behavior can be described as the features of the original EV scenario: static universe, basic ship image behavior, normal missions, with basic use of ncbs, except for stuff that's mandatory or that would break the consistency with the default Nova scenario (such as the 600×400 image here), and things that are so simple (such as BuyRandom) that everyone can understand them.
-After the list of fields, if there are, the hard-linked resources (such as the corresponding desc for outfits)
-Things that can be of interest in the Bible that's not useful to repeat in the annoted template.
-then, the maximum number of resources there can be of this kind, and as a consequence the IDs that can be used for them (128 to 127+nb) (notice I did it the other way round here, since there is no limit other than the one imposed by the IDs for dëscs), and the fact that the name of the resource is not used by the engine, if applicable, and other such paraphernalia that do not have to do with the data inside the resource.

Notice that things that are likely to be a popup menu, as well as flags, should have a basic labels (such as the one I put for the flags there) so that the reader can fastly match it with the corrsponding checkbox/popup menu item in his editor; as usual it won't be an exact match but he has to get used to it.

That's all for now, maybe I'll need to add some things if I realise they are needed while making other annoted templates. By the way, the "Note:"'s are not to be reput in other annoted templates. Also, all flags will be described when the turn of the first flags field of the resource comes, and the other flag fields will be ignored as already covered.

------------------
The (url="http://"https://secure.ambrosiasw.com/cgi-bin/store/hazel.cgi?action=serve&item;=breakdown.html&BREAKDOWN;_SKUID=1480")Ambrosia Mac CD(/url) with other registrations - 5$. Paying for (url="http://"http://www.ambrosiasw.com/games/evn/")EV Nova(/url) as it's such a great game - 30$.
The (url="http://"http://www.ambrosiasw.com/games/evn/tshirts.html")1337 EV Nova T-shirt(/url)(url="http://"http://www.ambrosiasw.com/webboard/Forum25/HTML/000003.html#ZachaPedro05-18-200409:42AM") (/url) - 22$. The (url="http://"http://w00tware.ev-nova.net/")NovaTools(/url) by wOOtWare to tinker with your Nova - FREE!
The feeling you're a Nova geek - priceless.
There are things money can't buy or that are free, for everything else, there's indeed Mastercard.

Dr. Trowel

Huzzah!

Quite informative. Good work!

orcaloverbri9

I could HTMLize these too, if you'd like—but it would take a while, as lately I've been loaded with homework.

Pulls out math and sighs because he already knows all this crap Why do we need to go over the order of operations in Algebra I? Meh...oh well.

------------------
The programmer's code of entomology: there's always another bug.
There are 10 types of people in the world: those who understand binary and those who have friends.
Windows users: stop asking for plugins. (url="http://"http://www.aznt.com/EVN/EVNEW/")Make one yourself.(/url)
(url="http://"http://www.cwssoftware.com")Sephil Saga Website(/url) | (url="http://"http://www.evula.org/infernostudios/search.html")Add-ons Search Engine(/url)

Zacha Pedro

Don't feel you have to do it; from now on I'm just throwing my guides into the wild for anyone that wishes to put in his plug helping site.

However, I'm sad to report that one drawback of switching to this invision BB software is you can no longer use character entities for accented chars: ë

orcaloverbri9

Are these going on SP's site?

As a side note, he still hasn't put up the BFD (I prefer BFD to BETD).

I wish they'd get the old interface back up. This doesn't feel right.

Zacha Pedro

orcaloverbri9, on Sep 7 2004, 02:00 AM, said:

Are these going on SP's site?

As a side note, he still hasn't put up the BFD (I prefer BFD to BETD).

I wish they'd get the old interface back up. This doesn't feel right.
View Post

I'm leaving the decision to SP; I know this work won't be unused, at least, even if it remains as a topic here. It's actually there, just he hasn't linked to it anywhere:http://www.evula.org.../guides/bfd.php (which is quite the same as not being there, I admit).BTW, as I put in the linky sticky topicky, among ourselves I prefer BFD for quick, just that "for" would have meant (to dummies) the guide would replace the Bible, which it doesn't, and BED is out of the question.

This post has been edited by Zacha Pedro : 07 September 2004 - 03:25 PM

SpacePirate

I'm going to bump this... I remember you posted a few of these right around the transition period, and I know that I missed them. This is the second of three I've found...

~ SP