SCI Wiki - User contributions [en]

Laura Bow II Programming Style Manual

2018-04-15T19:25:27Z

Omer Mor: /* Notes */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#Overlay Modules|1.4 Overlay Modules]] and [[#Pre-loading Resources (Optimization)|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may be positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an ''else'' clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approachVerbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||
<syntaxhighlight lang="sci">
(= x 17)
(= foobar 29)
(x doit: y z)
(foobar rescind: TRUE)</syntaxhighlight>
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T19:07:15Z

Omer Mor: /* Setting Up the Cast */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#Overlay Modules|1.4 Overlay Modules]] and [[#Pre-loading Resources (Optimization)|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may be positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an ''else'' clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approachVerbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T19:05:49Z

Omer Mor: /* Initial Code Based on Previous Room */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#Overlay Modules|1.4 Overlay Modules]] and [[#Pre-loading Resources (Optimization)|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may be positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an ''else'' clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T19:04:12Z

Omer Mor: /* Setting Up Ego */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#Overlay Modules|1.4 Overlay Modules]] and [[#Pre-loading Resources (Optimization)|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may be positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T19:02:43Z

Omer Mor: /* Pre-loading Resources */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#Overlay Modules|1.4 Overlay Modules]] and [[#Pre-loading Resources (Optimization)|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T19:02:12Z

Omer Mor: /* Pre-loading Resources */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#OverlayModules|1.4 Overlay Modules]] and [[#Pre-loading Resources (Optimization)|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:59:36Z

Omer Mor: /* Pre-loading Resources */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:58:13Z

Omer Mor: /* Room Init */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method is one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code in the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the: top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:50:30Z

Omer Mor: /* Overlay Modules */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the room is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method ill one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code is the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the: cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the: top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:41:06Z

Omer Mor: /* Public Entries & Externals */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>If you are receiving a '''NOT AN OBJECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance myActor of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the mom is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method ill one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code is the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the: cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the: top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:31:33Z

Omer Mor: /* Procedures */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>1f you are receiving a '''NOT AN 08JECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance ''myActor'' of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the mom is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method ill one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code is the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the: cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the: top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:29:50Z

Omer Mor: /* The Order or Things */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a-procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>1f you are receiving a '''NOT AN 08JECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance ''myActor'' of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the mom is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method ill one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code is the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the: cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the: top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Laura Bow II Programming Style Manual

2018-04-15T18:28:30Z

Omer Mor: /* Module Organization */

[[Official SCI Documentation]]<br />

<div align="center" style="font-size: 22pt">Laura Bow II Programming Style Manual</div><br />
<div align="center" style="font-size: 14pt">Coding Preference Of [[Brian K. Hughes]]</div>

This is an attempt at a programming style manual. It is intended to provide the reader with a list of my coding styles, and the DOs and DON'Ts of coding on [[Dagger of Amon Ra|Laura Bow II]]. ''It is not intended to be an authorized representation of Sierra coding policies''. While many of the rules listed in this document are no more than the personal preferences of a demented lead programmer (yours truly), I hope that the majority of this material will become ingrained in your programmer-self and carried on to your next project. Obviously, I'd like to see everyone adopt my coding style, but I am not the only lead programmer here. Just as I like things my way, so another lead may like it differently. The best we can hope: for, therefore, is a union of styles; if we all code alike, it really doesn't matter if it's my way or someone else's.

Please keep in mind that the information in this document is not carved in stone (but only because my printer has trouble feeding slabs of granite). If you have a serious objection to a concept herein, or feel you have a more efficient way to achieve the desired result, feel free to contact me. I firmly believe that one who is in a teaching capacity must spend roughly half his time learning as well.



==<br /> Module Organization ==

Arranging the elements of your module in a particular order makes the code much easier to read and maintain by others. Generally, grouping object by type is the easiest, although sometimes it is more logical to group objects by subject. For example, an actor could be grouped with all the other actors, or with his mover, sound, and script. Either way is acceptable.

Clearly mark your groups so that they can be found easily. A distinguishable comment before a group of items is the easiest way to do this. I have a macro, called [[MakeBox]], which will create a double-lined box around a piece of text. I will be happy to provide this macro to anyone who wants to adopt its style.

===<br /> The Order or Things ===

The following chart represents how I like to organize a file. You need not adhere to it strictly, but I strongly recommend it. Items marked with a § are required for every module.

<blockquote><blockquote>
header comments<ref>Header comments should include the name and purpose of the module, the author, the date last Updated, and a list of any classes defined in the module.</ref><br />
Script #<br />
includes<br />
procedure list<br />
public entry list<br />
defines<br />
locals<br />
instance of LBRoom<br />
procedures<br />
scripts<br />
Actors & Props<br />
Talkers & related objects<br />
View & PicViews<br />
Features<br />
Sound, Code, & Misc
</blockquote></blockquote>

===<br /> Procedures ===

In the above list, you'll, notice that I recommend procedures do not come before the instance of room. The rationale behind this is that that main object in the module (the room instance in room modules) should be the first code encountered. Some modules may contain several long procedures. It is inconvenient to one perusing the file to have to page-up and page-down through these procedures to see what the main object looks like.

Be aware of your coworkers' procedures. If there is a-procedure already written that may be used again with little or no modification, it may be beneficial to break the procedure out of the module in which it resides, put it into room 0 or other public module, and create an external reference define for it in '''[[GAME.SH]]'''.

(? Is room0 public ? )

===<br /> Public Entries & Externals ===

Any object that will be referenced outside the module in which it resides must be assigned a public entry number in that module. As an example, an instance of room in a room module must be assigned public entry number 0. This is how ''Game startRoom'' knows about the room<ref>1f you are receiving a '''NOT AN 08JECT: $0''' error when Game startRoom tries to add your room to the regions list, check to see if you've forgotten the public entry for your instance of LBRoom.</ref>. Public objects are referenced in other modules via the ''[[ScriptID()|ScriptID]]'' kernel call. ''ScriptID'' takes as parameters the number of the module in which our public object resides and the public entry number assigned to it, and returns an address to that object. For example, given:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(script# 100)

(public
myActor0
)

(instance ''myActor'' of Actor)</syntaxhighlight></blockquote>

we can reference ''myActor'' from another module with ''(ScriptID 100 0)''

If you will be referencing an object more than once, you should create a define for the ''ScriptID'' call. In the above example, we could save the object ID of ''myActor'' for use in several places, by creating the following define:

''(define xMyActor<ref>Refer to section
[[#5.4 Defines. Globals. Flags. & Vars|5.4 Defines. Globals. Flags. & Vars]] for more information on this syntax.</ref> (ScriptID 100 0))''

Procedures may be referenced externally as well as objects. The process is the same for objects and procedures, but our procedures will be referenced through extern statements in '''[[GAME.SH]]'''. These work the same as the ''ScriptID'' statement above, but generate a different PMachine op code.

===<br /> Overlay Modules ===

Overlay modules are modules that contain objects related to, but not always necessary for, a room module. You should review the code situation very carefully before splitting code out into an overlay module. Overlays are often difficult to manage, and can be very tricky as far as memory management. By contrast, however, they are not as difficult to create as they seem. Overlays should be considered if:

*§ The total size of the source module is approaching 64K
*§ There is a group of objects or large amount of code that is used only in a specific situation
*§ The amount of hunk available when running the mom is less than 5K
*§ There is a group of objects or large amount of code that can be shared by other modules<br /> 

Creating an overlay module is a relatively simple process. Refining it, however, may take some time and will most certainly break the original module temporarily. To create an overlay module, do the following:

*§ Create a new file with an appropriate name
*§ Move the code to be split out into the new module
*§ Create public entries in the original module for objects that must be referenced in the overlay
*§ Create external reference defines in the overlay to point to the public entries in the original module
*§ Crete public entries in the overlay for objects that must be referenced in the original module
*§ Create external reference defines in the original module to point to the public entries in the overlay
*§ Be sure that either the original module or the overlay itself removes the overlay from memory when finished with it

The hardest part about creating overlay modules is getting the external referencing correct. '''NOT AN OBJECT''' will generally mean that one of the two modules is trying to send a message to an object that is no longer in that module. '''DISPATCH NUMBER TOO LARGE''' generally is caused by trying to reference a public entry that is larger than the last public entry for that module. For example, the error will occur if (ScriptID 100 3) is used in one module and script# 100 only contains public entries 0, 1, and 2.

==<br /> Object Organization ==

How you layout your objects' code is nearly as important as how you layout the module, in terms of style. For most objects, this section is not important. But for a few objects such as rooms, these guidelines are recommended.

===<br /> Room ''Init'' ===
The ''room'' is one of the most common objects in the game, and the room's ''init'' method ill one of the most frequently referenced. It is fairly important, therefore, to keep the room's ''init'' method clean and easily readable. One way in which this can be accomplished is to order your room's ''init'' code is the following way:

# Pre-loading Resources
# Setting the region, if any
# Setting up ego<ref>Ego must generally be inited before the ''(super init:)'', if the room is an instance of a subclass of Room that handles walking ego in and out of rooms.</ref>
# Initial code based on previous room
# ''Super init:''
# Setting up Polygons
# Setting up the: cast
# Setting up features
# Miscellaneous initial code
# Setting script(s)

====<br /> Pre-loading Resources ====

All views, pics, sounds, cursors, and fonts used in the module should be loaded here. This serves two purposes: 1) to annotate which resources are being used (better than comments at the: top of the file), and 2) to prevent "disk hits" during the execution of a room, the theory being that if all the resources are loaded the game should never require disk access until another room change.<ref>If all resources have been pre-loaded and disk access is still occurring, this may indicate that the room is "hunk heavy" and prone to thrashing. See also sections [[#1.4 Overlay Modules|1.4 Overlay Modules]] and [[#3.2 Pre-loading Resources|3.2 Pre-loading Resources]].</ref>

====<br /> Setting the Region ====

Setting the room to a region (or vice versa, depending upon how you choose to look at it) is accomplished with the ''(self setRegions: regionModuleNum)'' statement, where ''regionModuleNum'' will usually be a define from '''[[GAME.SH]]'''.

====<br /> Setting Up Ego ====

Setting up ego will normally consist of two messages, an ''init'' and a ''normalize''. Additionally, ego may positioned here or have alternate cyclers and movers set. Note that the game's ''startRoom'' method will put a StopWalk cycler on ego by default. Except in extreme cases, you should not alter ego's ''edgeHit'' property here.

====<br /> Initial Code Based on Previous Room ====

Any initial code based on the previous room, such as positioning ego or setting vars, is accomplished by the ''(switch prevRoomNum)'' statement, as follows:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(switch prevRoomNum
(north
[code if coming from the north]
)
(south
[code if coming from the south]
)
)</syntaxhighlight></blockquote>

It is helpful to include an else clause that sets debugging information when teleporting.

====<br /> Super Init: ====

The ''(super init:)'' statement causes the super class, Room or a subclass thereof, to perform its initialization code. Among other things, this code draws the picture and sets ego to walk into the room (if appropriate).

====<br /> Setting Up Polygons ====

This is where polygons should be added to the room's obstacles list. They may be created dynamically (the normal output from the polygon editor) or be static instances that are simply added to the list.

====<br /> Setting Up the Cast ====

This is where all the Actors, Props, Views, and PicViews are initialized. From a size standpoint, it is cheaper to send complex messages here than to override the object's ''init'' method. For example:

<blockquote>''(object init:, approach Verbs: verbList)''</blockquote>

====<br /> Setting Up Features ====

Features should all be initialized in one place to make locating them later easier. Features should he initialized individually, just like other objects<ref>For more information on features see also section [[#2.3 A Word About Features|2.3 A Word About Features]].</ref>. As with objects in the cast, it is better to have complex messages here than in the Feature's ''init'' method.

====<br /> Miscellaneous Initial Code ====

This is where other initialization code should go. I strongly suggest annotating this code well to make it as clear as possible.

====<br /> Setting Script(s) ====

Finally, the ''init'' method of a room should set any scripts that need to be executed upon entering a room. Sometimes another ''switch'' is required to set different scripts based on the previous room.

===<br /> Dynamic Objects ===

A dynamic object is a clone of an object, an exact duplicate. They are useful when you need ''an'' object, but don't care ''which'' object. For example, you might need a temporary list to hold numbers for a sort routine. A dynamic list can be used just like any instance of List, but does not require an instance in the module. In the debugger's object list, a dynamic object will be preceded by an asterisk and will bear the same name as the object from which it was cloned. There are two ways to create a dynamic object: ''(theObj new:)'' and ''(Clone theObj)''. Whenever possible, the new method should be used instead of the kernel call.

Because dynamic objects allocate space off the heap instead of hunk, it is important to set a variable to the object's address so that it may be disposed of later. Orphaned dynamic objects (those left "hanging" with no handle to them) can cause frags or heap problems. By the same token, the number of dynamic objects in memory at one time should be monitored carefully. Too many objects can lead to low heap problems.

===<br /> A Word About Features ===

The notion that it is more efficient to add all the features to the features list and then in it them all is incorrect. Since the ''init'' method of Feature adds the object to the feature list, it is redundant to add it manually before the init. For example:

{|
|-
|valign="top" width="50"|Replace||<syntaxhighlight lang="sci">(features
add:
object1
object2
object3,
eachElementDo: #init
)</syntaxhighlight>||valign="top"|with||valign="top"|<syntaxhighlight lang="sci">(object1 init:)
(object2 init:)
(object3 init:)</syntaxhighlight>
|}

Features created with the on-line feature writer will have simple nsRects that define the area for which the ''onMe'' method will return TRUE, thus claiming an event. This "claim area" can be redefined by:

*§ redefining the ''onMe'' method
*§ setting the ''SKIPCHECK'' signal bit
*§ setting the ''onMeCheck'' property to a control color
*§ setting the ''onMeCheck'' property to an instance of polygon

Redefining the ''onMe'' method is by far the most versatile, though often not the most convenient. Setting the ''[[SKIPCHECK]]'' bit in the signal property is very easy and requires no changes to the view or the code. Setting the ''onMeCheck'' property to a control color is also very easy, but requires a change to the picture. Of the three, I recommend using ''SKIPCHECK'' wherever possible.

This brings us to dynamic polygons in features. Creating a dynamic polygon in the features ''init'' method, then putting its object ID into the ''onMeCheck'' property is inefficient at best and dangerous at worst. Not only does this method require redefining the ''init'' and ''dispose'' methods to create and dispose the polygon, but each dynamic polygon created will allocate approximately 300 bytes off the heap. In a room with 25 such features, up to 7,500 bytes of heap could be allocated by dynamic polygons. In addition, should you forget to dispose of the polygon in the feature's dispose method, the resulting frag can be very difficult and time-consuming to trace. I strongly advise against this method of defining features.

A word about addToPics: Whenever the ''[[addToPic()|addToPic]]'' method of a [[VIEW|View]], [[Prop Class|Prop]], or [[Actor Class|Actor]] is invoked, two things happen. First, a ''[[PicView Class|PicView]]'' clone is created and added to the ''addToPics'' list. It will have all the properties of the original object, but will be named "''PicView''". Second, the original object will be removed from the cast and added to the features list. This is NOT a dynamic object, but the original object itself.

===<br /> Annotation ===

When faced with the decision of throwing something away, my father used this rule of thumb: If he hadn't used it in the last year, he figured he'd never use it again and it got tossed. The same rule of thumb applies to commented code. Lines of code are usually commented because:

*§ they aren't needed any more
*§ they have been temporarily replaced by new code
*§ they have been permanently replaced by new code
*§ they have been temporarily removed for testing<br />

If your commented code falls into any of the first three categories and you have not re-instated it within two to three days, remove it. Old commented code is a waste of space and makes reading the uncommented code more difficult.

When dealing with objects, there are two areas in particular where I like to see comments. The first is immediately following a method declaration, unless the function is obvious, and the second is following each new method and property declared in a class. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj of Prop
(method (doit)
; I like to see comments here unless the code
; in this method is really obvious
)
)

(class myClass kindof Prop
(properties
fooBar ; Explain what this property does!
)
(methods
setFooBar ; Explain what this method does!
)
)</syntaxhighlight></blockquote>

Additionally, I have found that it is helpful to comment the closing paren of a method or object, especially if the code is more than 30 or 40 lines. When scrolling through a file it helps to be able to identify the object that immediately precedes the code I'm reading. For example:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(instance myObj ofProp
(method (init)

) ;Don't need a comment here
(method (doit)
... 50 lines ...
) ;end doit < -Nice to have this!
) ;end myObj < -Nice to have this, too!</syntaxhighlight></blockquote>

The general rule is: If you can set: both the method declaration and closing paren without touching the arrow keys or Page Up or Page Down, a comment is unnecessary.

Most people have customized their comment macros to insert special characters after the semicolon. For instance, your comments might look like this: ;§§. Some people use their initials, as in: ''';SRC''' or ''';BH'''. These are helpful in determining who has changed code.

==<br /> Optimization ==

We are pushing toward single-platform development, which means that once the game is shipping on the IBM platform, we would like to e able to roll it over to the Macintosh and Amiga with no significant changes to code or other resources. Granted, this will require many changes to our existing system and tools. But even when the all else has been done to that effect, the single largest responsibility lies with us, the lowly application' programmers: Optimization. It won't do us any good to be able to roll a game over to the 4.77 MHz Amiga in 2.6 hours flat, if it runs like a slug when it's there.

We have to take the responsibility <u>at the lime the code is designed and written</u> to ensure that it will run as efficiently as possible on even the slowest machines. That does not mean, however, that we have to sacrifice animation to the point where the game becomes a slide show on a fire-breathing 386 or 486 machine. There ill a happy medium, which is well-designed and well-written code that respects machine performance variations.

The worst offenders, in terms of speed and efficiency, are:

<blockquote>
*§ ''doit'' methods with code that need not be done every cycle
*§ sending messages each time information is needed instead of setting a variable the first time and using it in subsequent code
*§ not making certain animating objects are stop-updated or even added to pic when possible
*§ not implementing detail level
*§ not preloading resources
*§ bad overlay module management
*§ inefficient code layout and lack of encapsulation
*§ "Band-Aids", "quick fixes", "patches", "prophylactic code"</blockquote>

If you have any questions about the best way to accomplish a task, ask me. If I don't know I'll be happy to find out.

===<br /> The Dreaded Doit ===

''Doit'' methods are really neat. Every game cycle each object that has a ''doit'' method gels a shot at stardom. Imagine that each object with a ''doit'' method is a lead programmer and that one game cycle is one project status meeting. The more material each one has to report and the more inefficiently he presents his report, the more time will be required to get around to everyone and the longer the lead meeting will take. Now imagine that Ken Williams has mandated that the project status meeting will take no more than 30 minutes. To fit within this time constraint each lead has to report only the material necessary in a clear, concise manner. Likewise, each ''doit'' method needs to contain only the code necessary and in a clear, concise syntax.

Every message sent takes lime to execute and 16 bytes of compiled object code. Therefore, every message you can avoid in a doit is that much less overhead. If you will be checking an object's property or the return value from an object's method repeatedly, set a variable the first time, then use it for all subsequent checks.

Most of all, remember that objects have minds of their own; they have properties to remember data and methods to facilitate actions and reactions. They don't need to be babysat by a ''doit'' method. For instance, in the following ''doit'' code:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= = (theMusic prevSignal?) -l)
(theScript cue:)
)</syntaxhighlight></blockquote>

a message is sent to ''theMusic'' and a comparison is done each and every game cycle. This sort of code should be replaced by the following lines, where the music is first played:

''(theMusic play: theScript)''

===<br /> Pre-loading Resources (Optimization) ===

Every time the interpreter needs a view, picture, sound, cursor, font, or script that is not in memory, it has to go searching on the disk. Even on a fast hard drive this can cause pauses in the animation that can ruin the continuity of a scene. These "disk hits" can be avoided by simply pre-loading every resource the room will use, before it tries to use them. As explained in section 2.1, these pre-loads should be done at the very beginning of a room's ''init'' method, using the following statement:

<blockquote>''(Load resourceType resourceNumber resourceNumber...)''</blockquote>

where ''[[resourceType]]'' is one of the resource type definitions in '''[[SYSTEM.SH]]'''. Following the resource type is a list of all the resources of that type you wish to load, as in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(Load VIEW
vEgoDying
vEgoLaughing
)
(Load CURSOR
exitCursor
walkCursor
)
(Load SCRIPT ABOUTCODE)</syntaxhighlight></blockquote>

You can use the '''-c''' option when running the interpreter to help you find disk hits in your room. This option will cause the cursor to change to a disk drive icon whenever a resource is loaded. No disk cursor means no disk hits.

===<br /> Messaging ===

A message can either invoke a method of an object. set a property. or query a property. The syntax rules are as follows:

<blockquote><blockquote>
{|
|-
|width="200"|invoking a method:||''(object method: parameters)''
|-
|setting a property:||''(object property: expression)''
|-
|querying a property:||''(object property?)''
|}
</blockquote></blockquote>

While the punctuation following the selector (: and ?) arc optional to the compiler, they are <u>required</u> by me.

As mentioned in [[#The Dreaded Doit|section 3.1]] every message sent to an object requires 16 bytes of compiled object code. When you consider that often times there are many messages sent that you can't see in your code, the total number of messages passed during the execution of one little room is astounding.

For this reason it is important to optimize your messaging as much as possible. Store the result of a message if you will be using it frequently. Often this can be done in-line with other code. all in:

<blockquote><div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if(= theObj (theScript client?))
(theObj posn: 100 100)
)</syntaxhighlight></blockquote>

By storing the result of ''(theScript client?)'' in the variable ''theObj'', we have saved ourselves from having to query ''theScript'''s client every time we want to use it.

==<br /> Indention ==

More than any other factor, indention style can make code very readable or impossible to read. Different college instructors teach different methods, depending on their background and the language they teach, but here is the way I want to see code indented:

*§ Set your tabs in [[BRIEF]] to 4. 7. This means the first lab is at column four and every lab thereafter is three columns apart.
*§ As a general rule, all statements in method, procedure, ''if'' or ''cond'' block, ''while'' or ''for'' loop, or ''switch'' statement should be indented to the nearest common column
*§ Values in property lists should be indented to the nearest common column ([[#Example1|see Example 1 below]])
*§ Parameters in complex messages should be indented to the nearest common column ([[#Example2|see Example 2 below]])
*§ Closing parens should be outdented to the same column as their match
*§ Expressions in and or or statement should be indented to the nearest common column (see Example 3 below)
*§ The first expressing following an ''and'', ''or'', or ''not'' statement should be on the same line as the statement ([[#Example3|see Example 3 below]])
*§ Values in consecutive ''define'' statements should be indented to the nearest common column
*§ Initial values of local variables should be indented to the nearest common column
*§ Array elements should be indented to the nearest common column following either the array name or the open bracket ([[#Example4|see Example 4 below]])

===<br /> Tabs vs. Spaces ===

[[BRIEF]] will allow you to fill columns to the left of text with either tabs or spaces. I prefer tabs because they are easier to manage when moving code around. Get into the habit of using the TAB and SHIFT-TAB keys to indent and outdent blocks of code. You'll save lots of time over manually inserting and deleting spaces.

===<br /> In ''If'' Blocks ===

All statements that belong to a specific condition should be indented to the same column. Likewise, all expressions should be so aligned, with the first expression following an ''and'', ''or'', or ''not'' statement falling on the same line as the statement. ([[#Example3|See Example 3 for details]] or talk to me).

===<br /> In Properties Lists ===

Values in properties lists should be indented to the nearest common tab, meaning that they will be aligned vertically in the tab position closest to the longest property name. I have a [[BRIEF#BRIEF Macros|BRIEF macro]] that automatically aligned property values which I will be happy to give you. ([[#Example1|see Example 1 for details]]).

===<br /> In Complex Messages ===

Similar to values in a properties list, parameters in a complex message should be indented to the nearest common tab. They should be aligned vertically in the tab position closest to the longest selector name. I have a BRIEF macro that automatically aligns complex message parameters which I will be happy to give you. ([[#Example2|See Example 2 for details]]).

===<br /> In Arrays ===

Initial values in arrays should be aligned with the nearest common tab following either the array name or the open bracket. While I prefer moving the open bracket to the line following the array name and indenting it one tab, this is against standard C coding conventions and so I won't enforce it. The indention of the array elements, however, is required. ([[#Example4|See Example 4 for details]]).

===<br /> Blank Lines ===

Blank lines can be very helpful in setting groups of related statements apart from each other. I don't have any hard fast rules about using blank lines; use your best judgment. If a blank line makes the code easier to read, put one in.

===<br /> Examples ===

<div ID="Example1"></div>'''Example 1: Indention of property values'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(properties
x 5,
Y 5,
view 100
)</syntaxhighlight>

<div ID="Example2"></div>'''Example 2: Indention of complex message parameters'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(theObj
setLoop: 0,
setCel: 0,
setCycle: Forward
)</syntaxhighlight>

<div ID="Example3"></div>'''Example 3: Indention of expressions'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(if (and (= = theView 100)
(or (theObj isKindOf. Thing)
(theObj responds To: thingValue)
)
)
(Print "Foo to all")
)</syntaxhighlight>

<div ID="Example4"></div>'''Example 4: Indention of array elements
'''

<div class="CodeBlockHeader">SCI Code:</div>
<syntaxhighlight lang="sci">
(local or (local
myArray = myArray = [
[ valuel
value1 value2
value2 ]
] )
)</syntaxhighlight>

==<br /> Naming Conventions ==

There are a few Sierra standards concerning the naming of variables and objects that we will be using. Note: that capitalization is essential. The standard conventions are:

<blockquote><blockquote>
{|
|-
|width="250"|globals, locals, temps ||''globalName''
|-
|flags ||''tFlagName''
|-
|point flags ||''ptFlagName''
|-
|defines, point ||''ptsDefineName''
|-
|defines, text substitution ||''defineName''
|-
|defines, numeric constant ||''DEFINE_NAME''
|-
|defines, external reference ||''xDefineName''
|-
|classes ||''ClassName''
|-
|procedures ||''ProcedureName''
|-
|inventory enums ||''iInvItemName''
|-
|views ||''vViewName''
|-
|inventory views ||''ivViewName''
|-
|pictures ||''pPictureName''
|-
|actors ||''aActorName''
|-
|talkers ||''tTalkerName''
|-
|scripts ||''sScriptName''
|-
|musIc ||''mMusicName''
|-
|sounds ||''nSoundName''
|}
</blockquote></blockquote>

If you can think of other defines that should be in this list, let me know.

==<br /> The Part at the End ==

In general, keep your code as clean and efficient as possible. Again, the rules in this text are not set in cement. Any comments or suggestions will certainly be <strike>laughed at</strike> considered.

The first time any of you break the above rules, you will be told nicely. The second time you will be told firmly. The third time I will personally dull all your pencils so they won't stick in the ceiling anymore, change all occurrences of your name in the source code to Arvin Slatherlord Loudermilk III, and force you to take lunch lit 8:35 am for a week. So there.

==<br /> Notes ==

From [[Corey Cole|Corey]]<span style="float: right">1/3/92  </span>
<br />To [[Brian K. Hughes|Brian]]

<div style="font-size: 14pt">Comments on LB2 Programming Manual</div>

<ol>
<li>I like it.</li>
<li>[[#Blank_Lines|Page 13-- Blank lines]]<br />I like blank lines between all major blocks, objects, methods procedures, etc. Also after large blocks within methods (e.g. cond's, etc.)</li>
<li>[[#In Arrays|Page 13 -- example 4 (indentation of array elements)]]. Don't worry about "c" standards -- Your first (preferred) approach is more readable should be the standard.</li>
<li>Add to indentation standards: When sending messages or assigning values to several objects or variables in a row, indent to common tab.</li>
</ol>
<blockquote><blockquote>
{|
|-
| width="100" valign="top"|Examples:||''( = x 17)''<br />''( = foobar 29)''<br />''(x doit: y 2)''<br />''(foobar resind: TRUE)''
|}
</blockquote></blockquote>
<ol start="5">
<li>[[#Naming Conventions|Page 14]] -- I like your different naming conventions. How about ''dDefineName'' for text sub defines so they don't look like variables (I've been using ''DefineName'', but could switch).</li>
<li>[[#Messaging|Page 11 -- Messaging]] -- I use "?" when invoking a method which solely returns a value (i.e. a "property-like" method) -- "?" is for questions, ":" for <span class="Alert">imper?</span></li>
</ol>

==<br /> References ==

<references />

==<br /> Related Links ==

* [[Design Documents]]
* [[:Category:Scripting|Scripting]]

[[Media:Laura_Bow_II_-_Programming_Style_Manual.pdf|Download the original Laura Bow II Programming Style Manual in PDF Form]]

[[Category:References]]
[[Category:SCI Documentation]]
[[Category:Scripting]]

Jeff Stephenson

2015-12-08T18:45:29Z

Omer Mor:

Stub

Jeff Stephenson

[[File:Jeff_Stephenson.jpg]]

Jeff Stephenson
Designer & Programmer
1982-1993

Jeff Stephenson created SCI (Sierra's Creative Interpreter), the object-oriented scripting language of Sierra On-Line for its adventure games after the older AGI (a procedural language). Previously, he also was the head of Sierra’s AGI and SCI system programmers and responsible for much of the code of both of those languages. He originally called it LSCI, for Large-model Script Code Interpreter, and later SCI because it ran scripts, until someone in marketing found a better way to explain the acronym.

He was one of the company's first employees, struggling through the down times when Sierra almost went under. When Sierra got back on track, development began on King's Quest.

In the early nineties, as Sierra's Lead Programmer, he was also involved with creating TSN (The Sierra Network), later INN (The ImagiNation Network), the architecture for online games. In 1992, he left the company for good.

Educational Background:

Program Development, Interface Development

Where Is He Now?:

http://sciprogramming.com/community/index.php?topic=369.30

http://www.mobygames.com/developer/sheet/view/developerId,52/

http://www.allowe.com/games/larry/inside-stories/larryland.html

I'm probably the last to know this, but anyway:
Jeff Stephenson is the brain behind Sierra's SCI fame, and also partly responsible for AGI. He's came up with the encryption string "AVIS DURGAN" used in AGI resources. Turns out Avis Durgan is not only a string, it is also the name of his wife, and lately they had some financial troubles which they shared with a reporter:
http://www.marketplace.org/topics/your-money/borrowers/good-credit-not-immune-cuts

Programming/Engineering - gameography

* Crazy Nick's Picks: King Graham's Board Game Challenge (1993), Sierra On-Line, Inc.
* The Dagger of Amon Ra (1992), Sierra On-Line, Inc.
* Jones in the Fast Lane (Enhanced CDROM version) (1992), Sierra On-Line, Inc.
* Quest for Glory III: Wages of War (1992), Sierra On-Line, Inc.
* Castle of Dr. Brain (1991), Sierra On-Line, Inc.
* Conquests of the Longbow: The Legend of Robin Hood (1991), Sierra On-Line, Inc.
* EcoQuest: The Search for Cetus (1991), Sierra On-Line, Inc.
* Hoyle Official Book of Games: Volume 3 (1991), Sierra On-Line, Inc.
* Jones in the Fast Lane (1991), Sierra On-Line, Inc.
* Leisure Suit Larry 1: In the Land of the Lounge Lizards (1991), Sierra On-Line, Inc.
* Leisure Suit Larry 5: Passionate Patti Does a Little Undercover Work (1991), Sierra On-Line, Inc.
* Police Quest 3: The Kindred (1991), Sierra On-Line, Inc.
* Roberta Williams' Mixed-Up Mother Goose (1991), Sierra On-Line, Inc.
* Space Quest I: Roger Wilco in the Sarien Encounter (1991), Sierra On-Line, Inc.
* Space Quest IV: Roger Wilco and the Time Rippers (1991), Sierra On-Line, Inc.
* Conquests of Camelot: The Search for the Grail (1990), Sierra On-Line, Inc.
* Hoyle Official Book of Games: Volume 2 (1990), Sierra On-Line, Inc.
* King's Quest V: Absence Makes the Heart Go Yonder! (1990), Sierra On-Line, Inc.
* Mixed-Up Mother Goose (1991), Sierra On-Line, Inc.
* Quest for Glory II: Trial by Fire (1990), Sierra On-Line, Inc.
* Codename: ICEMAN (1989), Sierra On-Line, Inc.
* The Colonel's Bequest (1989), Sierra On-Line, Inc.
* Hero's Quest: So You Want To Be A Hero (1989), Sierra On-Line, Inc.
* Hoyle Official Book of Games: Volume 1 (1989), Sierra On-Line, Inc.
* Leisure Suit Larry III: Passionate Patti in Pursuit of the Pulsating Pectorals (1989), Sierra On-Line, Inc.
* Manhunter 2: San Francisco (1989), Sierra On-Line, Inc.
* Space Quest III: The Pirates of Pestulon (1989), Sierra On-Line, Inc.
* Gold Rush! (1988), Sierra On-Line, Inc.
* King's Quest IV: The Perils of Rosella (1988), Sierra On-Line, Inc.
* Leisure Suit Larry Goes Looking for Love (In Several Wrong Places) (1988), Sierra On-Line, Inc.
* Manhunter: New York (1988), Sierra On-Line, Inc.
* Police Quest 2: The Vengeance (1988), Sierra On-Line, Inc.
* Leisure Suit Larry in the Land of the Lounge Lizards (1987), Sierra On-Line, Inc.
* Police Quest: In Pursuit of the Death Angel (1987), Sierra On-Line, Inc.
* Space Quest II: Chapter II - Vohaul's Revenge (1987), Sierra On-Line, Inc.
* The Black Cauldron (1986), Sierra On-Line, Inc.
* King's Quest III: To Heir is Human (1986), Sierra On-Line, Inc.
* Space Quest: The Sarien Encounter (1986), Sierra On-Line, Inc.
* King's Quest II: Romancing the Throne (1985), Sierra On-Line, Inc.
* Donald Duck's Playground (1986), Sierra On-Line, Inc.
* King's Quest (1984), Sierra On-Line, Inc.
* Hi-Res Adventure #4: Ulysses and the Golden Fleece (1982), Sierra On-Line, Inc.
* Hi-Res Adventure #2: The Wizard and the Princess (1982), IBM

Design - gameography

* Mixed-Up Fairy Tales (1991), Sierra On-Line, Inc.
* King's Quest V: Absence Makes the Heart Go Yonder! (1990), Sierra On-Line, Inc.
* Roberta Williams' King's Quest I: Quest for the Crown (1990), Sierra On-Line, Inc.
* Leisure Suit Larry Goes Looking for Love (In Several Wrong Places) (1988), Sierra On-Line, Inc.
* Manhunter: New York (1988), Sierra On-Line, Inc.
* Police Quest 2: The Vengeance (1988), Sierra On-Line, Inc.
* Space Quest II: Chapter II - Vohaul's Revenge (1987), Sierra On-Line, Inc.
* Space Quest: The Sarien Encounter (1986), Sierra On-Line, Inc.
* King's Quest (1984), Sierra On-Line, Inc.

Other - gameography

* Police Quest: In Pursuit of the Death Angel (1992), Sierra On-Line, Inc.
* Police Quest 3: The Kindred (1991), Sierra On-Line, Inc.
* Leisure Suit Larry III: Passionate Patti in Pursuit of the Pulsating Pectorals (1989), Sierra On-Line, Inc.
* King's Quest (1984), Sierra On-Line, Inc.

Production - gameography

Hi-Res Adventure #5: Time Zone (1982), On-Line Systems

The Script Programming Language/Data Types and Variables

2015-12-01T21:02:16Z

Omer Mor: /* Pointers: */

[[The Original SCI Documentation]]<br />

<div align="center">
Chapter:
[[The Script Programming Language/Introduction|1]] |
[[The Script Programming Language/Files|2]] |
[[The Script Programming Language/Definitions|3]] |
[[The Script Programming Language/Data Types and Variables|4]] |
[[The Script Programming Language/Primitive Procedures|5]] |
[[The Script Programming Language/Control Flow|6]] |
[[The Script Programming Language/Procedures|7]] |
[[The Script Programming Language/Using SC|8]] |
[[The Script Programming Language/Index|Index]]
</div><br />

<div align="center"><span style="font-size: 22pt">The Script Programming Language</span><br />
<span style="font-size: 22pt">Data Types and Variables</span><br />
''Author: [[Jeff Stephenson]]''</div>

 

==<br /> Data Types and Variables ==

===<br /> Numbers: ===

All numbers in Script are 16 bit integers, giving a range of -32768 to +32767. Numbers may be written as decimal (1024), hex ($400), or binary (%10000000000).

===<br /> Variables: ===

Variables hold numbers. Variables can be either global, local, or temporary, depending on when they are created and destroyed:

'''Global variables''' are created when the program starts and destroyed when it ends, and are thus accessible to all scripts at all times.

'''Local variables''' are created when a logic script is loaded and destroyed when it is purged. They are thus only available when the logic script is loaded and will not retain a value through a purge-reload cycle. You will find that, as your programming takes on a more object-oriented flavor, you will use fewer and fewer local variables.

'''Temporary variables''' are created when a procedure or method is entered and destroyed when it is left. They are thus only available to the declaring procedure and do not retain a value between calls to the procedure.

In order to throw the 'link' out of the traditional 'edit-compile-
link-test' cycle of software development, YOU, rather than the linker, must
define the address (i.e. variable number) of global variables. This is done
with the global definition:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var-name var-number
var-name var-number
...
)
</syntaxhighlight>
</blockquote>

This defines var-name to be global variable number var-number.

Local variables, not being accessible outside of the scripts in which they are declared and thus not requiring linking, can have their addresses set by the Script compiler. There are two ways of defining locals:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var-name
var-name
...
)
</syntaxhighlight>
</blockquote>

defines a single variables with the names var-name.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local [array-name n])
</syntaxhighlight>
</blockquote>

defines an array of n elements with the name array-name (the brackets in this do NOT mean 'optional' -- they are required).

Multiple local variable definitions may be combined in one statement:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
[array1 10]
[array2 5]
var2
.
.
.
)
</syntaxhighlight>
</blockquote>

Temporary variables will be discussed in the section on user-defined procedures.

Define and enum statements may be included within both global and local variable definitions.

===<br /> Arrays: ===

To access element n of the array anArray, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[anArray n]
</syntaxhighlight>
</blockquote>

Despite the syntactic difference between local variable declarations and local array declarations, there really is no distinction between variables and arrays -- any variable may be indexed as an array. Thus, if we have the local variable declarations

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
var2
var3
var4
)
</syntaxhighlight>
</blockquote>

we can set the value of var1 to that of var4 by any of the following statements:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= var1 var4)
(= var1 [var2 2])
(= var1 [var3 1])
(= [var2 -1] [var1 3])
</syntaxhighlight>
</blockquote>

The first method is obviously the preferred method for clarity, but this array property of all variables allows access to variable numbers of parameters in a user-defined procedure (see section on user-defined procedures).

This property of variables is also the basis of the method by which you declare global arrays -- you simply leave an array-sized gap in the global variable numbering sequence. To declare var2 as a global array of 10 elements, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var1 23
var2 24
;10 element array
var3 34
)
</syntaxhighlight>
</blockquote>

and access var2 as an array:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[var2 7]
</syntaxhighlight>
</blockquote>

=== <br /> Pointers: ===

Some kernel calls require pointers to variables, rather than the value of a variable. A pointer to a variable is created by preceding a variable reference with the '<tt>@</tt>' sign. Pointers may be created to array elements as well as to simple variables:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
@ego ;pointer to the variable ego
@[foo 3] ;pointer to fourth element of array foo
</syntaxhighlight>
</blockquote>

Since there is currently no way in sc to dereference a pointer, this is only useful for passing pointers to kernel calls.

=== <br /> Text: ===

Text strings are strings of characters enclosed in double quotes, and may be used anywhere you like:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(Print "This is immediate text.")
</syntaxhighlight>
</blockquote>

prints the text string,

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= textToPrint "This text is referenced through a variable.")
</syntaxhighlight>
</blockquote>

sets the variable to a pointer to the text string, and

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(instance foo of Bar
(properties
name:"fooBar"
)
)
</syntaxhighlight>
</blockquote>

sets the name property of foo to be a pointer to the text string.

When sc goes to squirrel a text string away, it first checks to see if it
has seen the string before. If so, it just uses the previous text, rather
than duplicating the text. For long text strings which are used in several
places, however, the likelihood that you will manage to type the text
identically in each case is small. In this case you can simply put the text
in a define statement

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(define lotsOftext "This is a long text string. I am using a
define statement to avoid having to type
it repeatedly.")
</syntaxhighlight>
</blockquote>

This introduces another aspect of text strings: If text is too long fit on a single line, you may enter it on several lines. Multiple white-space (spaces, tabs, and newlines) gets converted to a single space, so the text above ends up with just one space between the words on each line. If you want multiple spaces, enter them as underbars, '<tt>_</tt>'. These are converted to spaces in the string, but are not compacted.

To include a '<tt>_</tt>' in text, type '<tt>\_</tt>', where '<tt>\</tt>' is the escape character. Explicit newlines are entered just as in C: '<tt>\n</tt>'. A CR/LF pair is entered as '<tt>\r</tt>' (the '<tt>\r</tt>' should be used in place of '<tt>\n</tt>' in all strings destined for a file). Characters which are not on the keyboard, but are defined in a font (such as the Sierra symbol in the menubar) can be included in the string by preceding the two-digit hex value of the character with the '<tt>\</tt>'. Thus, <code>"This is the Sierra symbol: \01"</code> would put the value 1 at the end of the string, and this character in the font is the Sierra symbol.

The maximum length of a text string is 2000 bytes.

=== <br /> Word-strings: ===

Word-strings are used to represent templates for user input in Said statements. A word-string is a string enclosed in single quotes which contains meta-characters describing the content of a sentence. The meta-characters and their meanings are described in the separate Vocabulary documentation.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(if (Said 'give/pirate/gold coins<#' @howMany)
(Print "Get lost creep.")
)
</syntaxhighlight>
</blockquote>

As with text strings, identical strings are stored only once.

=== <br /> Characters: ===

Characters are single ASCII characters, and are denoted by preceding the character with the reverse single quote ("tick") character:

<blockquote>
<code>`A</code> represents uppercase A and <br />
<code>`?</code> represents the question mark
</blockquote>

Several character sequences represent special key combinations:

<blockquote>
<code>`^a</code> represents ctrl-A <br />
<code>`@b</code> represents alt-B <br />
<code>`#4</code> represents the F4 key <br />
</blockquote>

=== <br /> Literal selectors: ===

Sometimes, as in the code

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(cast eachElementDo: #showSelf:)
</syntaxhighlight>
</blockquote>

you want to send the value of selector rather than use the selector as the start of another message to an object (these terms will be described in Object Oriented Programming in Script). Preceding the selector with a '#' produces the literal value of the selector rather than using it as a message.

 

;Notes
<references />

 

[[The Script Programming Language | Table of Contents]]

<span style="float: left">[[The Script Programming Language/Definitions | < Previous: Definitions]]</span><span style="float: right">[[The Script Programming Language/Primitive Procedures | Next: Primitive Procedures >]]</span>

 

[[Category:SCI Documentation]]

The Script Programming Language/Data Types and Variables

2015-12-01T21:01:49Z

Omer Mor: /* Text: */

[[The Original SCI Documentation]]<br />

<div align="center">
Chapter:
[[The Script Programming Language/Introduction|1]] |
[[The Script Programming Language/Files|2]] |
[[The Script Programming Language/Definitions|3]] |
[[The Script Programming Language/Data Types and Variables|4]] |
[[The Script Programming Language/Primitive Procedures|5]] |
[[The Script Programming Language/Control Flow|6]] |
[[The Script Programming Language/Procedures|7]] |
[[The Script Programming Language/Using SC|8]] |
[[The Script Programming Language/Index|Index]]
</div><br />

<div align="center"><span style="font-size: 22pt">The Script Programming Language</span><br />
<span style="font-size: 22pt">Data Types and Variables</span><br />
''Author: [[Jeff Stephenson]]''</div>

 

==<br /> Data Types and Variables ==

===<br /> Numbers: ===

All numbers in Script are 16 bit integers, giving a range of -32768 to +32767. Numbers may be written as decimal (1024), hex ($400), or binary (%10000000000).

===<br /> Variables: ===

Variables hold numbers. Variables can be either global, local, or temporary, depending on when they are created and destroyed:

'''Global variables''' are created when the program starts and destroyed when it ends, and are thus accessible to all scripts at all times.

'''Local variables''' are created when a logic script is loaded and destroyed when it is purged. They are thus only available when the logic script is loaded and will not retain a value through a purge-reload cycle. You will find that, as your programming takes on a more object-oriented flavor, you will use fewer and fewer local variables.

'''Temporary variables''' are created when a procedure or method is entered and destroyed when it is left. They are thus only available to the declaring procedure and do not retain a value between calls to the procedure.

In order to throw the 'link' out of the traditional 'edit-compile-
link-test' cycle of software development, YOU, rather than the linker, must
define the address (i.e. variable number) of global variables. This is done
with the global definition:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var-name var-number
var-name var-number
...
)
</syntaxhighlight>
</blockquote>

This defines var-name to be global variable number var-number.

Local variables, not being accessible outside of the scripts in which they are declared and thus not requiring linking, can have their addresses set by the Script compiler. There are two ways of defining locals:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var-name
var-name
...
)
</syntaxhighlight>
</blockquote>

defines a single variables with the names var-name.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local [array-name n])
</syntaxhighlight>
</blockquote>

defines an array of n elements with the name array-name (the brackets in this do NOT mean 'optional' -- they are required).

Multiple local variable definitions may be combined in one statement:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
[array1 10]
[array2 5]
var2
.
.
.
)
</syntaxhighlight>
</blockquote>

Temporary variables will be discussed in the section on user-defined procedures.

Define and enum statements may be included within both global and local variable definitions.

===<br /> Arrays: ===

To access element n of the array anArray, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[anArray n]
</syntaxhighlight>
</blockquote>

Despite the syntactic difference between local variable declarations and local array declarations, there really is no distinction between variables and arrays -- any variable may be indexed as an array. Thus, if we have the local variable declarations

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
var2
var3
var4
)
</syntaxhighlight>
</blockquote>

we can set the value of var1 to that of var4 by any of the following statements:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= var1 var4)
(= var1 [var2 2])
(= var1 [var3 1])
(= [var2 -1] [var1 3])
</syntaxhighlight>
</blockquote>

The first method is obviously the preferred method for clarity, but this array property of all variables allows access to variable numbers of parameters in a user-defined procedure (see section on user-defined procedures).

This property of variables is also the basis of the method by which you declare global arrays -- you simply leave an array-sized gap in the global variable numbering sequence. To declare var2 as a global array of 10 elements, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var1 23
var2 24
;10 element array
var3 34
)
</syntaxhighlight>
</blockquote>

and access var2 as an array:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[var2 7]
</syntaxhighlight>
</blockquote>

=== <br /> Pointers: ===

Some kernel calls require pointers to variables, rather than the value of a variable. A pointer to a variable is created by preceding a variable reference with the '@' sign. Pointers may be created to array elements as well as to simple variables:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
@ego ;pointer to the variable ego
@[foo 3] ;pointer to fourth element of array foo
</syntaxhighlight>
</blockquote>

Since there is currently no way in sc to dereference a pointer, this is only useful for passing pointers to kernel calls.

=== <br /> Text: ===

Text strings are strings of characters enclosed in double quotes, and may be used anywhere you like:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(Print "This is immediate text.")
</syntaxhighlight>
</blockquote>

prints the text string,

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= textToPrint "This text is referenced through a variable.")
</syntaxhighlight>
</blockquote>

sets the variable to a pointer to the text string, and

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(instance foo of Bar
(properties
name:"fooBar"
)
)
</syntaxhighlight>
</blockquote>

sets the name property of foo to be a pointer to the text string.

When sc goes to squirrel a text string away, it first checks to see if it
has seen the string before. If so, it just uses the previous text, rather
than duplicating the text. For long text strings which are used in several
places, however, the likelihood that you will manage to type the text
identically in each case is small. In this case you can simply put the text
in a define statement

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(define lotsOftext "This is a long text string. I am using a
define statement to avoid having to type
it repeatedly.")
</syntaxhighlight>
</blockquote>

This introduces another aspect of text strings: If text is too long fit on a single line, you may enter it on several lines. Multiple white-space (spaces, tabs, and newlines) gets converted to a single space, so the text above ends up with just one space between the words on each line. If you want multiple spaces, enter them as underbars, '<tt>_</tt>'. These are converted to spaces in the string, but are not compacted.

To include a '<tt>_</tt>' in text, type '<tt>\_</tt>', where '<tt>\</tt>' is the escape character. Explicit newlines are entered just as in C: '<tt>\n</tt>'. A CR/LF pair is entered as '<tt>\r</tt>' (the '<tt>\r</tt>' should be used in place of '<tt>\n</tt>' in all strings destined for a file). Characters which are not on the keyboard, but are defined in a font (such as the Sierra symbol in the menubar) can be included in the string by preceding the two-digit hex value of the character with the '<tt>\</tt>'. Thus, <code>"This is the Sierra symbol: \01"</code> would put the value 1 at the end of the string, and this character in the font is the Sierra symbol.

The maximum length of a text string is 2000 bytes.

=== <br /> Word-strings: ===

Word-strings are used to represent templates for user input in Said statements. A word-string is a string enclosed in single quotes which contains meta-characters describing the content of a sentence. The meta-characters and their meanings are described in the separate Vocabulary documentation.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(if (Said 'give/pirate/gold coins<#' @howMany)
(Print "Get lost creep.")
)
</syntaxhighlight>
</blockquote>

As with text strings, identical strings are stored only once.

=== <br /> Characters: ===

Characters are single ASCII characters, and are denoted by preceding the character with the reverse single quote ("tick") character:

<blockquote>
<code>`A</code> represents uppercase A and <br />
<code>`?</code> represents the question mark
</blockquote>

Several character sequences represent special key combinations:

<blockquote>
<code>`^a</code> represents ctrl-A <br />
<code>`@b</code> represents alt-B <br />
<code>`#4</code> represents the F4 key <br />
</blockquote>

=== <br /> Literal selectors: ===

Sometimes, as in the code

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(cast eachElementDo: #showSelf:)
</syntaxhighlight>
</blockquote>

you want to send the value of selector rather than use the selector as the start of another message to an object (these terms will be described in Object Oriented Programming in Script). Preceding the selector with a '#' produces the literal value of the selector rather than using it as a message.

 

;Notes
<references />

 

[[The Script Programming Language | Table of Contents]]

<span style="float: left">[[The Script Programming Language/Definitions | < Previous: Definitions]]</span><span style="float: right">[[The Script Programming Language/Primitive Procedures | Next: Primitive Procedures >]]</span>

 

[[Category:SCI Documentation]]

The Script Programming Language/Data Types and Variables

2015-12-01T20:53:29Z

Omer Mor: /* Characters: */

[[The Original SCI Documentation]]<br />

<div align="center">
Chapter:
[[The Script Programming Language/Introduction|1]] |
[[The Script Programming Language/Files|2]] |
[[The Script Programming Language/Definitions|3]] |
[[The Script Programming Language/Data Types and Variables|4]] |
[[The Script Programming Language/Primitive Procedures|5]] |
[[The Script Programming Language/Control Flow|6]] |
[[The Script Programming Language/Procedures|7]] |
[[The Script Programming Language/Using SC|8]] |
[[The Script Programming Language/Index|Index]]
</div><br />

<div align="center"><span style="font-size: 22pt">The Script Programming Language</span><br />
<span style="font-size: 22pt">Data Types and Variables</span><br />
''Author: [[Jeff Stephenson]]''</div>

 

==<br /> Data Types and Variables ==

===<br /> Numbers: ===

All numbers in Script are 16 bit integers, giving a range of -32768 to +32767. Numbers may be written as decimal (1024), hex ($400), or binary (%10000000000).

===<br /> Variables: ===

Variables hold numbers. Variables can be either global, local, or temporary, depending on when they are created and destroyed:

'''Global variables''' are created when the program starts and destroyed when it ends, and are thus accessible to all scripts at all times.

'''Local variables''' are created when a logic script is loaded and destroyed when it is purged. They are thus only available when the logic script is loaded and will not retain a value through a purge-reload cycle. You will find that, as your programming takes on a more object-oriented flavor, you will use fewer and fewer local variables.

'''Temporary variables''' are created when a procedure or method is entered and destroyed when it is left. They are thus only available to the declaring procedure and do not retain a value between calls to the procedure.

In order to throw the 'link' out of the traditional 'edit-compile-
link-test' cycle of software development, YOU, rather than the linker, must
define the address (i.e. variable number) of global variables. This is done
with the global definition:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var-name var-number
var-name var-number
...
)
</syntaxhighlight>
</blockquote>

This defines var-name to be global variable number var-number.

Local variables, not being accessible outside of the scripts in which they are declared and thus not requiring linking, can have their addresses set by the Script compiler. There are two ways of defining locals:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var-name
var-name
...
)
</syntaxhighlight>
</blockquote>

defines a single variables with the names var-name.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local [array-name n])
</syntaxhighlight>
</blockquote>

defines an array of n elements with the name array-name (the brackets in this do NOT mean 'optional' -- they are required).

Multiple local variable definitions may be combined in one statement:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
[array1 10]
[array2 5]
var2
.
.
.
)
</syntaxhighlight>
</blockquote>

Temporary variables will be discussed in the section on user-defined procedures.

Define and enum statements may be included within both global and local variable definitions.

===<br /> Arrays: ===

To access element n of the array anArray, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[anArray n]
</syntaxhighlight>
</blockquote>

Despite the syntactic difference between local variable declarations and local array declarations, there really is no distinction between variables and arrays -- any variable may be indexed as an array. Thus, if we have the local variable declarations

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
var2
var3
var4
)
</syntaxhighlight>
</blockquote>

we can set the value of var1 to that of var4 by any of the following statements:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= var1 var4)
(= var1 [var2 2])
(= var1 [var3 1])
(= [var2 -1] [var1 3])
</syntaxhighlight>
</blockquote>

The first method is obviously the preferred method for clarity, but this array property of all variables allows access to variable numbers of parameters in a user-defined procedure (see section on user-defined procedures).

This property of variables is also the basis of the method by which you declare global arrays -- you simply leave an array-sized gap in the global variable numbering sequence. To declare var2 as a global array of 10 elements, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var1 23
var2 24
;10 element array
var3 34
)
</syntaxhighlight>
</blockquote>

and access var2 as an array:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[var2 7]
</syntaxhighlight>
</blockquote>

=== <br /> Pointers: ===

Some kernel calls require pointers to variables, rather than the value of a variable. A pointer to a variable is created by preceding a variable reference with the '@' sign. Pointers may be created to array elements as well as to simple variables:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
@ego ;pointer to the variable ego
@[foo 3] ;pointer to fourth element of array foo
</syntaxhighlight>
</blockquote>

Since there is currently no way in sc to dereference a pointer, this is only useful for passing pointers to kernel calls.

=== <br /> Text: ===

Text strings are strings of characters enclosed in double quotes, and may be used anywhere you like:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(Print "This is immediate text.")
</syntaxhighlight>
</blockquote>

prints the text string,

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= textToPrint "This text is referenced through a variable.")
</syntaxhighlight>
</blockquote>

sets the variable to a pointer to the text string, and

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(instance foo of Bar
(properties
name:"fooBar"
)
)
</syntaxhighlight>
</blockquote>

sets the name property of foo to be a pointer to the text string.

When sc goes to squirrel a text string away, it first checks to see if it
has seen the string before. If so, it just uses the previous text, rather
than duplicating the text. For long text strings which are used in several
places, however, the likelihood that you will manage to type the text
identically in each case is small. In this case you can simply put the text
in a define statement

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(define lotsOftext "This is a long text string. I am using a
define statement to avoid having to type
it repeatedly.")
</syntaxhighlight>
</blockquote>

This introduces another aspect of text strings: If text is too long fit on a single line, you may enter it on several lines. Multiple white-space (spaces, tabs, and newlines) gets converted to a single space, so the text above ends up with just one space between the words on each line. If you want multiple spaces, enter them as underbars, '_'. These are converted to spaces in the string, but are not compacted.

To include a '_' in text, type '\_', where '\' is the escape character. Explicit newlines are entered just as in C: '\n'. A CR/LF pair is entered as '\r' (the '\r' should be used in place of '\n' in all strings destined for a file). Characters which are not on the keyboard, but are defined in a font (such as the Sierra symbol in the menubar) can be included in the string by preceding the two-digit hex value of the character with the '\'. Thus, "This is the Sierra symbol: \01" would put the value 1 at the end of the string, and this character in the font is the Sierra symbol.

The maximum length of a text string is 2000 bytes.

=== <br /> Word-strings: ===

Word-strings are used to represent templates for user input in Said statements. A word-string is a string enclosed in single quotes which contains meta-characters describing the content of a sentence. The meta-characters and their meanings are described in the separate Vocabulary documentation.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(if (Said 'give/pirate/gold coins<#' @howMany)
(Print "Get lost creep.")
)
</syntaxhighlight>
</blockquote>

As with text strings, identical strings are stored only once.

=== <br /> Characters: ===

Characters are single ASCII characters, and are denoted by preceding the character with the reverse single quote ("tick") character:

<blockquote>
<code>`A</code> represents uppercase A and <br />
<code>`?</code> represents the question mark
</blockquote>

Several character sequences represent special key combinations:

<blockquote>
<code>`^a</code> represents ctrl-A <br />
<code>`@b</code> represents alt-B <br />
<code>`#4</code> represents the F4 key <br />
</blockquote>

=== <br /> Literal selectors: ===

Sometimes, as in the code

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(cast eachElementDo: #showSelf:)
</syntaxhighlight>
</blockquote>

you want to send the value of selector rather than use the selector as the start of another message to an object (these terms will be described in Object Oriented Programming in Script). Preceding the selector with a '#' produces the literal value of the selector rather than using it as a message.

 

;Notes
<references />

 

[[The Script Programming Language | Table of Contents]]

<span style="float: left">[[The Script Programming Language/Definitions | < Previous: Definitions]]</span><span style="float: right">[[The Script Programming Language/Primitive Procedures | Next: Primitive Procedures >]]</span>

 

[[Category:SCI Documentation]]

The Script Programming Language/Data Types and Variables

2015-12-01T20:47:06Z

Omer Mor: /* Text: */

[[The Original SCI Documentation]]<br />

<div align="center">
Chapter:
[[The Script Programming Language/Introduction|1]] |
[[The Script Programming Language/Files|2]] |
[[The Script Programming Language/Definitions|3]] |
[[The Script Programming Language/Data Types and Variables|4]] |
[[The Script Programming Language/Primitive Procedures|5]] |
[[The Script Programming Language/Control Flow|6]] |
[[The Script Programming Language/Procedures|7]] |
[[The Script Programming Language/Using SC|8]] |
[[The Script Programming Language/Index|Index]]
</div><br />

<div align="center"><span style="font-size: 22pt">The Script Programming Language</span><br />
<span style="font-size: 22pt">Data Types and Variables</span><br />
''Author: [[Jeff Stephenson]]''</div>

 

==<br /> Data Types and Variables ==

===<br /> Numbers: ===

All numbers in Script are 16 bit integers, giving a range of -32768 to +32767. Numbers may be written as decimal (1024), hex ($400), or binary (%10000000000).

===<br /> Variables: ===

Variables hold numbers. Variables can be either global, local, or temporary, depending on when they are created and destroyed:

'''Global variables''' are created when the program starts and destroyed when it ends, and are thus accessible to all scripts at all times.

'''Local variables''' are created when a logic script is loaded and destroyed when it is purged. They are thus only available when the logic script is loaded and will not retain a value through a purge-reload cycle. You will find that, as your programming takes on a more object-oriented flavor, you will use fewer and fewer local variables.

'''Temporary variables''' are created when a procedure or method is entered and destroyed when it is left. They are thus only available to the declaring procedure and do not retain a value between calls to the procedure.

In order to throw the 'link' out of the traditional 'edit-compile-
link-test' cycle of software development, YOU, rather than the linker, must
define the address (i.e. variable number) of global variables. This is done
with the global definition:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var-name var-number
var-name var-number
...
)
</syntaxhighlight>
</blockquote>

This defines var-name to be global variable number var-number.

Local variables, not being accessible outside of the scripts in which they are declared and thus not requiring linking, can have their addresses set by the Script compiler. There are two ways of defining locals:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var-name
var-name
...
)
</syntaxhighlight>
</blockquote>

defines a single variables with the names var-name.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local [array-name n])
</syntaxhighlight>
</blockquote>

defines an array of n elements with the name array-name (the brackets in this do NOT mean 'optional' -- they are required).

Multiple local variable definitions may be combined in one statement:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
[array1 10]
[array2 5]
var2
.
.
.
)
</syntaxhighlight>
</blockquote>

Temporary variables will be discussed in the section on user-defined procedures.

Define and enum statements may be included within both global and local variable definitions.

===<br /> Arrays: ===

To access element n of the array anArray, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[anArray n]
</syntaxhighlight>
</blockquote>

Despite the syntactic difference between local variable declarations and local array declarations, there really is no distinction between variables and arrays -- any variable may be indexed as an array. Thus, if we have the local variable declarations

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(local
var1
var2
var3
var4
)
</syntaxhighlight>
</blockquote>

we can set the value of var1 to that of var4 by any of the following statements:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= var1 var4)
(= var1 [var2 2])
(= var1 [var3 1])
(= [var2 -1] [var1 3])
</syntaxhighlight>
</blockquote>

The first method is obviously the preferred method for clarity, but this array property of all variables allows access to variable numbers of parameters in a user-defined procedure (see section on user-defined procedures).

This property of variables is also the basis of the method by which you declare global arrays -- you simply leave an array-sized gap in the global variable numbering sequence. To declare var2 as a global array of 10 elements, write

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(global
var1 23
var2 24
;10 element array
var3 34
)
</syntaxhighlight>
</blockquote>

and access var2 as an array:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
[var2 7]
</syntaxhighlight>
</blockquote>

=== <br /> Pointers: ===

Some kernel calls require pointers to variables, rather than the value of a variable. A pointer to a variable is created by preceding a variable reference with the '@' sign. Pointers may be created to array elements as well as to simple variables:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
@ego ;pointer to the variable ego
@[foo 3] ;pointer to fourth element of array foo
</syntaxhighlight>
</blockquote>

Since there is currently no way in sc to dereference a pointer, this is only useful for passing pointers to kernel calls.

=== <br /> Text: ===

Text strings are strings of characters enclosed in double quotes, and may be used anywhere you like:

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(Print "This is immediate text.")
</syntaxhighlight>
</blockquote>

prints the text string,

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(= textToPrint "This text is referenced through a variable.")
</syntaxhighlight>
</blockquote>

sets the variable to a pointer to the text string, and

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(instance foo of Bar
(properties
name:"fooBar"
)
)
</syntaxhighlight>
</blockquote>

sets the name property of foo to be a pointer to the text string.

When sc goes to squirrel a text string away, it first checks to see if it
has seen the string before. If so, it just uses the previous text, rather
than duplicating the text. For long text strings which are used in several
places, however, the likelihood that you will manage to type the text
identically in each case is small. In this case you can simply put the text
in a define statement

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(define lotsOftext "This is a long text string. I am using a
define statement to avoid having to type
it repeatedly.")
</syntaxhighlight>
</blockquote>

This introduces another aspect of text strings: If text is too long fit on a single line, you may enter it on several lines. Multiple white-space (spaces, tabs, and newlines) gets converted to a single space, so the text above ends up with just one space between the words on each line. If you want multiple spaces, enter them as underbars, '_'. These are converted to spaces in the string, but are not compacted.

To include a '_' in text, type '\_', where '\' is the escape character. Explicit newlines are entered just as in C: '\n'. A CR/LF pair is entered as '\r' (the '\r' should be used in place of '\n' in all strings destined for a file). Characters which are not on the keyboard, but are defined in a font (such as the Sierra symbol in the menubar) can be included in the string by preceding the two-digit hex value of the character with the '\'. Thus, "This is the Sierra symbol: \01" would put the value 1 at the end of the string, and this character in the font is the Sierra symbol.

The maximum length of a text string is 2000 bytes.

=== <br /> Word-strings: ===

Word-strings are used to represent templates for user input in Said statements. A word-string is a string enclosed in single quotes which contains meta-characters describing the content of a sentence. The meta-characters and their meanings are described in the separate Vocabulary documentation.

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(if (Said 'give/pirate/gold coins<#' @howMany)
(Print "Get lost creep.")
)
</syntaxhighlight>
</blockquote>

As with text strings, identical strings are stored only once.

=== <br /> Characters: ===

Characters are single ASCII characters, and are denoted by preceding the character with the reverse single quote ("tick") character:

<blockquote>
`A represents uppercase A and
`? represents the question mark
</blockquote>

Several character sequences represent special key combinations:

<blockquote>
`^a represents ctrl-A
`@b represents alt-B
`#4 represents the F4 key
</blockquote>

=== <br /> Literal selectors: ===

Sometimes, as in the code

<blockquote>
<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">
(cast eachElementDo: #showSelf:)
</syntaxhighlight>
</blockquote>

you want to send the value of selector rather than use the selector as the start of another message to an object (these terms will be described in Object Oriented Programming in Script). Preceding the selector with a '#' produces the literal value of the selector rather than using it as a message.

 

;Notes
<references />

 

[[The Script Programming Language | Table of Contents]]

<span style="float: left">[[The Script Programming Language/Definitions | < Previous: Definitions]]</span><span style="float: right">[[The Script Programming Language/Primitive Procedures | Next: Primitive Procedures >]]</span>

 

[[Category:SCI Documentation]]

The Script Programming Language/Introduction

2015-12-01T20:33:16Z

Omer Mor:

SCI Tutorials

2015-11-28T22:28:41Z

Omer Mor:

These are the tutorials that we currently have available. They cover a beginner's getting started level to more advanced topics.

 

* [[SCI Studio Tutorial 1|Brian Provinciano's SCI Studio Tutorial 1]]<br />
* [[SCI Studio Tutorial 2|Brian Provinciano's SCI Studio Tutorial 2]]<br />
* [[Advanced SCI Tutorials|Phil Fortier's Advanced SCI Tutorials]]<br />
* [[SCI Point and Click Tutorial|Cloudee1's SCI Point and Click Tutorial]]
* [[Adding Sound Support|Brandon Blume's Adding Sound Support]]
* [[Official SCI Documentation]]
* [http://scicompanion.com/Documentation/index.html SCI Companion Documentation]

 

<span style="float: right">[[SCI_Studio_Tutorial 1|Next: Brian Provinciano's SCI Studio Tutorial 1 >]]</span>

 

[[Category:Tutorials]]

Official SCI Documentation

2015-11-28T20:03:35Z

Omer Mor:

[[Media:SCRIPT.pdf|The Script Programming Language]]<br />
[[Media:KERNEL.pdf|SCI Kernel Documentation]]<br />
[[Media:OBJECT.pdf|Object Oriented Programming in Script]]<br />
[[Media:CLASS.pdf|Script Classes for Adventure Games]]<br />
[[Media:NLPDOC.pdf|SCI Parser Programmer's Reference]]<br />
[[Media:Run_Time_System_Changes.pdf|Run Time System Changes]]<br />
[[Media:SCI_Changes_&_Updates.pdf|SCI Changes & Updates]]<br />

Official SCI Documentation

2015-11-28T20:03:11Z

Omer Mor:

Official SCI Documentation

2015-11-28T20:02:44Z

Omer Mor:

File:SCI Changes & Updates.pdf

2015-11-28T20:02:04Z

Omer Mor: SCI Changes & Updates

SCI Changes & Updates

File:Run Time System Changes.pdf

2015-11-28T20:00:04Z

Omer Mor: Run Time System Changes

Run Time System Changes

Official SCI Documentation

2015-11-28T18:30:26Z

Omer Mor:

File:NLPDOC.pdf

2015-11-28T18:29:20Z

Omer Mor: SCI Parser Programmer's Reference

SCI Parser Programmer's Reference

File:CLASS.pdf

2015-11-28T11:02:03Z

Omer Mor: Script Classes for Adventure Games

Script Classes for Adventure Games

Official SCI Documentation

2015-11-28T11:01:31Z

Omer Mor:

Official SCI Documentation

2015-11-28T09:33:25Z

Omer Mor: Adding Official SCI Documentation

[[Media:SCRIPT.pdf|The Script Programming Language]]<br />
[[Media:KERNEL.pdf|SCI Kernel Documentation]]<br />
[[Media:OBJECT.pdf|Object Oriented Programming in Script]]<br />

File:KERNEL.pdf

2015-11-28T09:24:55Z

Omer Mor: SCI Kernel Documentation

SCI Kernel Documentation

File:OBJECT.pdf

2015-11-28T09:22:54Z

Omer Mor: Object Oriented Programming in Script

Object Oriented Programming in Script

File:SCRIPT.pdf

2015-11-28T09:21:46Z

Omer Mor: The Script Programming Language

The Script Programming Language

SCI Tutorials

2015-11-28T09:20:14Z

Omer Mor:

These are the tutorials that we currently have available. They cover a beginner's getting started level to more advanced topics.

 

* [[SCI Studio Tutorial 1|Brian Provinciano's SCI Studio Tutorial 1]]<br />
* [[SCI Studio Tutorial 2|Brian Provinciano's SCI Studio Tutorial 2]]<br />
* [[Advanced SCI Tutorials|Phil Fortier's Advanced SCI Tutorials]]<br />
* [[SCI Point and Click Tutorial|Cloudee1's SCI Point and Click Tutorial]]
* [[Adding Sound Support|Brandon Blume's Adding Sound Support]]
* [[Official SCI Documentation]]

 

<span style="float: right">[[SCI_Studio_Tutorial 1|Next: Brian Provinciano's SCI Studio Tutorial 1 >]]</span>

 

[[Category:Tutorials]]

Fonts

2015-07-05T20:03:56Z

Omer Mor:

== Sierra System ==
[[File:Sierra_System.png]]

== Sierra Serif ==

== Sierra Sans ==

== Sierra Small ==

== Heir Serif Bold ==

== Wilco Serif ==

== Sierra Debug ==

== Sierra Large ==

File:Sierra System.png

2015-07-05T20:02:45Z

Omer Mor:

Fonts

2015-07-04T08:10:50Z

Omer Mor:

== Sierra System ==
[[File:Example.jpg]]

== Sierra Serif ==

== Sierra Sans ==

== Sierra Small ==

== Heir Serif Bold ==

== Wilco Serif ==

== Sierra Debug ==

== Sierra Large ==

Fonts

2015-07-04T08:05:16Z

Omer Mor: Created page with " == Sierra System == File:Example.jpg"

== Sierra System ==
[[File:Example.jpg]]

SCI Companion

2011-12-15T17:41:13Z

Omer Mor: /* SCI Companion */ Added link to SCI Companion source code repository on github

==Integrated Development Environments==

There are two IDEs publicly available for SCI development. The first is SCI Studio, by Brian Provinciano and the second, SCI Companion, by Phil Fortier. Both original authors have since abandoned any further development.

 

===<div align="center">SCI Companion</div>===

<div align="center">[[File:SCICompanion.png|SCICompanion.png]]</div>

Complete editor for EGA SCI games. Inspired by SCIStudio. You can edit pics, views, script source code, text resources, cursors, fonts, the main vocab file, even create new games.

Download from the [http://www.mtnphil.com/Games/SCIComp.html SCI Companion homepage] or download from here:

* [[Image:ZIP.GIF|ZIP File]][[SCI:SCITools/SCIComp.zip|SCICompanion Version 2.1.0.5 with help file]]<span class="DLInfo"> (ZIP file) [2.50 MB]</span>

Source Code is available here:

* [https://github.com/OmerMor/SciCompanion SCI Companion Repository on GitHub]

 

===<div align="center">SCI Studio 3</div>===

<div align="center">[[File:SCI-Studio3.png| SCI Studio 3]]</div>

Brian Provinciano's original tool for creating EGA SCI games. Home page no longer exists. SCI Studio 3 is that last release version of his IDE, but it has certain stability issues. Brian Provinciano was developing a version of SCI Studio that could open and create the SCI1 VGA games before he abandoned all work on Studio.

* [[Image:ZIP.GIF|ZIP File]][[SCI:SCITools/SCIStudio3/SCI_Studio_30_(30129).zip|SCI Studio 3.0]]<span class="DLInfo"> (ZIP file) [1.70 MB]</span>
** [[Image:ZIP.GIF|ZIP File]][[SCI:SCITools/SCIStudio3/SCI_Studio_30_Source(20030316).zip|CI Studio 3.0 Source]]<span class="DLInfo"> (ZIP file) [510 KB]</span>
* [[Image:ZIP.GIF|ZIP File]][[SCI:SCITools/SCIStudio3/SCI_Studio_30_Template_Game.zip|SCI Studio 3 Template Game]]<span class="DLInfo"> (ZIP file) [156 KB]</span>


The original project's site no longer exists, however, the source of SCI Studio is available and has been placed on SVN at SourceForge. The current SCI Studio's site on SourceForge can be found at http://scistudio.sourceforge.net/

 

===<div align="center">SCI Studio 4 (VGA)</div>===

Brian Provinciano's unfinished work to add support for the SCI VGA games.

* [[Image:ZIP.GIF|ZIP File]][[SCI:SCITools/SCI_Studio_VGA.zip|SCI Studio 4 (VGA)]]<span class="DLInfo"> (ZIP file) [1.63 MB]</span>
** [[Image:ZIP.GIF|ZIP File]][[SCI:SCITools/SCI_Studio_VGA_Development_Source_Code.zip|SCI Studio 4 (VGA) Source]]<span class="DLInfo"> (ZIP file) [3.02 MB]</span>

 

[[Category:SCI Tools]]