SCI Companion documentation

[MusicallyInspired]

Just leave the British/Canadian spellings like "colour" in there. That's proper.

Nice work! Very modern and clean.

[OmerMor]

Excellent documentation!

I have a question regarding the template class system:
Do we have to retain the original names, even when they're obscure or abbreviated?
For example, why not rename SRDialog to SaveRestoreDialog? Osc to Oscillator? CT to CycleTo?

And what the meaning of SQEgo? Is it supposed to be Space Quest Ego?

What about SQ5? Why not TemplateGame/CustomGame?

[Kawa]

Do we have to retain the original names, even when they're obscure or abbreviated?
For example, why not rename SRDialog to SaveRestoreDialog? Osc to Oscillator? CT to CycleTo?

Good call!

And what the meaning of SQEgo? Is it supposed to be Space Quest Ego?

Yes it is, and I've been wondering about that too. It's certainly allowed to be [your game initials here]Ego...

What about SQ5? Why not TemplateGame/CustomGame?

...unlike this, because ScummVM is a DummyVM that won't recognize your game if it isn't named right. Doesn't need to be SQ5 though...

[troflip]

Excellent documentation!

I have a question regarding the template class system:
Do we have to retain the original names, even when they're obscure or abbreviated?
For example, why not rename SRDialog to SaveRestoreDialog? Osc to Oscillator? CT to CycleTo?

And what the meaning of SQEgo? Is it supposed to be Space Quest Ego?

What about SQ5? Why not TemplateGame/CustomGame?

Regarding SQ5 for the game name, this is required so that it works in ScummVM (otherwise, ScummVM will throw its hands up and say, "I don't recognize this game"). I should probably get ScummVM to add explicit support for recognizing SCI1.1 template games.

SQEgo could probably re-named. Any suggestions? TemplateEgo? I could possibly fold it into Ego too.

As for renaming, I'm leaning towards keeping the original names. I actually had renamed some... like for instance, the SCI1.1 template game still had a class called class255_0. I renamed it to GUIControl, but then I ran into issues with documentation when I needed to refer to "GUIControl for the SCI1.1 template game, or Control for the SCI0 template game", so I figured it was best to keep names similar between SCI0 and SCI1.1 as much as possible (and so I changed it to "Control"). Admittedly, this may have been a unique case, as this was in the kernel documentation which applies to both SCI0 and SCI1.1.

Like, for backwards compatibility, we shouldn't really change the SCI0 names. And I think there is value in keeping SCI0 and SCI1.1 names the same as much as possible (of course, there are some that were different, like Act vs Actor). Then again... a new template is an opportunity to make things a little better, so...

Of note, the next version of the SCI 1.1 template game will change a filename: View.sc becomes Actor.sc. I never did like the View.sc filename, but I did this mainly because the original name Sierra used was Actor.sc (based on the debug opcodes in some SCI2 games).

[OmerMor]

I think readable names trumps documentation backward compatibility. It should also be easy to rename the sci0 template names to the new ones.

What about adding some class diagrams to the documentation?
I made an example for the Ego class hierarchy. I think it turned out too large so it'd probably be best to draw less classes per diagram next time:


This is the diagram source in yUML format:

Code: [Select]

[Obj||init();doit();dispose();showStr(buffer);showSelf();perform(object ［...］);isKindOf(className);isMemberOf(theClass);respondsTo(selectorName);yourself()]

[Feature|x;y;z;heading;noun;modNum;nsTop;nsLeft;nsBottom;nsRight;sightAngle;actions;onMeCheck;state;approachX;approachY;approachDist;_approachVerbs|init(［initCode］);dispose();initialize(param1);handleEvent(pEvent);doVerb(theVerb);notFacing();facingMe(［theObj］);isNotHidden();onMe(theObj);onMe(x y);approachVerbs(［verbs ...］);setName(theName);setOnMeCheck(omcDISABLE);setOnMeCheck(omcPOLYGON polygon);setOnMeCheck(omcCOLORS ［colors ...］)]

[View|yStep;view;loop;cel;priority;underBits;signal;lsTop;lsLeft;lsBottom;lsRight;brTop;brLeft;brBottom;brRight;scaleSignal;scaleX;scaleY;maxScale|init();dispose();showSelf();isNotHidden();onMe(x y);onMe(obj);posn(theX theY ［theZ］);stopUpd();forceUpd();startUpd();setPri(thePriority);setLoop(theLoop);setCel(theCel);ignoreActors(shouldIgnore);hide();show();delete();addToPic();lastCel();motionCue();checkDetail();setScale(theScale)]

[Prop|cycleSpeed;timer;detailLevel|doit();handleEvent(pEvent);delete();motionCue();checkDetail(param1);setScale(class params);setScale(obj params);setScale(-1 otherObj);setScale(scale);setCycle(theCycler sendParams);setScript(theScript sendParams);cue()]

[Actor|illegalBits;xLast;yLast;xStep;origStep;moveSpeed;blocks;baseSetter;looper;viewer;avoider;code|init(params);doit();posn(theX theY ［theZ］);setLoop(loop);setLoop(loopClass ［params ...］);setLoop(looper ［params ...］);delete();motionCue();checkDetail(param1);setMotion(theMover sendParams);setAvoider(theAvoider sendParams);ignoreHorizon(param1);observeControl(bits);ignoreControl(bits);observeBlocks(block);ignoreBlocks(block);isStopped();isBlocked();inRect(left top right bottom);onControl(［fUsePoint］);distanceTo(obj);cantBeHere();setStep(newX newY ［fDontSetOrigStep］);setDirection(newDirection);setHeading(theHeading cueObj cueValues);setSpeed(newSpeed)]

[Ego|edgeHit|init();doit();handleEvent(pEvent);facingMe();get(invNumber ［...］);put(invNumber ［newOwner］);has(invNumber)]

[Obj]^-[Feature],[Feature]^-[View],[View]^-[Prop],[Prop]^-[Actor],[Actor]^-[Ego]
[Obj]^-[Script]
[Obj]^-[Code],[Code]^-[Scaler]
[Obj]^-[Motion]
[Obj]^-[Cycle]
[Prop]-script >[Script]
[Prop]-cycler >[Cycle]
[Prop]-scaler >[Scaler]
[Actor]-mover >[Motion]
[Motion]-client >[Actor]


[troflip]

Ok, let's see what other people think of switching to full names for things. Kawa seemed for it.

As for UML diagrams, if you want to make some that you think are useful, I could add them. Usually my biggest problem with these is that they "rot", although this class hierarchy isn't changing, so that's not really an issue here. I don't particularly find them useful for understanding a system (especially verbose ones that list all the properties and methods), but perhaps others do?

Thinking about it some more, I think perhaps a simple class hierarchy diagram for the commonly used classes could be useful, and like you had in your diagram, their relation to movers, loopers, etc...

Let's here from others... would this be useful?

[Kawa]

I like the extended class names as much as I don't like folding GIEgo into Ego

That's "Game Initials".

But yeah, diagrams might be good to have. Perhaps only show the class properties that reference other classes, so for example an Egoa View's scaler property connects to the Scaler class (itself connected to Code), but the scaleX, scaleY, and scaleSignal properties are left out. This would show, at a glance, that the scaler property takes a Scaler, while the cycler property takes Cycle... which in turn reveals it could take Fwd, StopWalk...

[OmerMor]

Here's an initial work on a class hierarchy diagram.

Todo:

• Use color, maybe to note the different class "families"
• Prune some esoteric classes to make it cleaner
• Add missing relations

[MusicallyInspired]

Would script code not look extra cluttered with all the long class/function names? Doesn't matter to me otherwise.

[Kawa]

Would script code not look extra cluttered with all the long class/function names? Doesn't matter to me otherwise.

(thing:view(13) loop(1) setCycle(Fwd)) versus (thing:view(13) loop(1) setCycle(Forward))? (class public ElysianFields of Region)? You be the judge.

After all, when do you expect to dig into SaveRestoreDialog?

[troflip]

Here's an initial work on a class hierarchy diagram.

So, a diagram that large is quite unwieldy. It's also pretty trivial to generate programmatically (SCI Companion has a dialog that lets you browse the class hierarchy in tree form - that is, the class hierarchy is readily available in code - so it would be trivial to spit out in .dot or some other kind of graph format - sphinx (the doc system I'm using) also has a plugin for generating graphs from text input), but as you said, it needs some "human" pruning.

I don't really want a large diagram like that in the official documentation. I'm trying to think of what is most useful for people. For instance, one option is to choose various core base classes (Feature, Motion, Cycler, Control, etc..) and the provide a class hierarchy diagram just for that on the doc page for that base class (or perhaps have special "features" "movers" "cyclers" pages that show the diagram). I'm not actually sure that the inheritance hierarchy is very useful anyway (who cares that MoveFwd inherits from PolyPath? All that matters is that it's a Motion class). I guess it's mildly interesting to see how Sierra designed things, but... (side rant: The SCI framework is typical of early object-oriented frameworks in that it is somewhat guilty of abusing class inheritance).

I think what's maybe more interesting is how the various classes interact (e.g. Actors need Movers and Cyclers, Rooms can have Scripts). What is a good way to show that?

[Collector]

I say yea on the extended class names. It makes it more apparent.

You had that class hierarchy in the old Companion. Gumby and I have already implemented such a feature in developer. You can export it to an XML. Something that unwieldy is probably better handled through something that is controllable like a treeview. Tutorials could use partial diagrams limited to the immediate subject.

[troflip]

Ok, well here are my proposals for renames:

Beg         Beginning
Blk         Block
Collect      Collection
CT         CycleTo
DPath      DirectedPath
Fwd         Forward
IconI      IconItem
Inv         Inventory
InvI         InventoryItem
InvItem      InventoryItem   -> seems like this can be combined with above class.
MCyc      ManualCycle
MoveFwd      MoveForward
Osc         Oscillate
PAvoider      PolyAvoider/PathAvoider      // Not sure about these....
PChase      PolyChase/PathChase
PFollow      PolyFollow/PathFollow
RandCycle   RandomCycle
RelDPath      RelativeDirectedPath
Rev         Reverse
Rgn         Region
Rm         Room
ROsc      ReverseOscillate
SL         StatusLine
SQEgo      GameEgo
SRDialog      SaveRestoreDialog
TO         TimerObject

[troflip]

You know, it just occurred to be that this might cause some issues with ScummVM. There are places where Scumm looks for classes by name to detect certain features. I poked around just a bit, and I already see one piece of code that looks for "Rm". This is making me think that the risk of changing the names might outweigh any benefit.

It's entirely possible it will cause some issues with Sierra's interpreters too. I'm sure most of the names are fine to change, but why risk it? If there is some particularly egregiously confusing name in a commonly used class, then maybe a few one-offs are ok (the Inv, InvI, InvItem, IconI come to mind).

[Collector]

Do we really need to worry about ScummVM? Outside of its debugger it does not really give anything over DOSBox. Ignoring it would also avoid its game recognition problem, too. The abbreviations are not very intuitive and could put off new users.