Castle Paradox

[Pepsi Ranger]

After reading a post about implementing strings, and remembering that the plotscript dictionary is still vague about how (and when) to use certain commands, I thought it might be nice to write examples of how and when to use them here. Maybe James can use them in the next version of the Plotscript Dictionary to give people a better roadmap how to use this stuff.

Prime example of what I'm asking for, taken directly from the current version of the Plotscript Dictionary:

"wait for text box"
Makes the script wait until there is no text box displaying on the screen. Useful to know when to move on after using a show text box command.

(Not only does it tell us what it does, but gives an example on when it's needed.)

Here's the starter list of commands that could use examples. This can be updated in chunks to prevent this from becoming an overwhelming project. The first few are close enough to being self explanatory that an update isn't necessary, but might still be helpful for those who really don't get it:

"wait for key (key)"

(current definition)

Waits for the player to press a key. You can use the follwing constants: any key, up key, down key, left key, right key, use key, cancel key, or menu key. If you do not specify, then any key will be used.

(what it needs)

Well, it needs to be proofread first ("following," not "follwing"). But outside of that, it should address a reason why one would use this instead of a scancode. Plenty of newbies will grow frustrated trying to get their heroes to dance when they could be advancing backdrops instead. (Or if they can use it to make a hero dance, an example might be helpful.)

"suspend obstruction"

(current definition)

Allows heros to walk through NPCs, allows NPCs to walk through heros, and allows NPCs to walk through each other. Use resume obstruction to restore normal obstruction behavior.

(what it needs)

Perhaps a line like: "This should be used to ensure the pathfinding NPC (or hero) gets to his target destination without another NPC stopping him along the way."

"suspend hero walls"

(current definition)

Allows heros to walk through walls. Use resume hero walls to restore normal wall behavior.

(what it needs)

Pretty much the same thing as above, but substitute "object stopping him" for "NPC stopping him."

"suspend box advance"

(current definition)

Prevents the player from advancing or clearing text boxes by pressing keys. While this is active, the only way to make a text box advance is with the advance text box command. Be very careful with this command, since you do not want to leave the player stuck on a text box forever.

(what it needs)

"Useful for cut scenes that play out like a movie, where the player just watches the dialogue unfold."

"suspend overlay"

(current definition)

Prevents overhead tiles from being drawn over heros and NPCs.

(what it needs)

Well, it probably doesn't need emphasis now that layers are active. But something like "Useful for creating bridges or catwalks that can be walked on or passed under" can work here.

"set hero frame (who, frame)"

(current definition)

Sets the walking frame of the specified hero to 0 or 1.

(what it needs)

Perhaps a reminder that the walking frame can be found in the Walkabout graphics set for that hero, and that the numbers determine the left or right frame of whatever direction the hero is facing.

"walk hero to x (who,x)"

(current definition)

Makes the specified hero walk to a given X coordinate on the map

(what it needs)

"Useful for outlining a travel path for the hero to follow during a 'suspend player' sequence."

"walk hero to y (who,x)"

(current definition)

Makes the specified hero walk to a given Y coordinate on the map

(what it needs)

The same as above, but also a minor proofread (it should be "walk hero to y (who,y)" not "(who,x)").

"check hero wall (who,direction)"

(current definition)

Returns true if there is a wall blocking the hero from moving in the specified direction. No actual movement takes place.

(what it needs)

A brief explanation why a plotscripter would want to use this (perhaps to tell the script to pick a new travel route for the hero).

"hero is walking (who)"

(current definition)

Returns true if the specified hero (by position in the caterpillar) is currently walking. Returns false if the hero is standing still.

(what it needs)

Same as above. Perhaps an example in plotscript form would help clarify how to use it, too.

"put hero (who,x,y)"

(current definition)

Moves a hero to a precise location on the map. The first argument is the her's position in the walkabout party. The second and third arguments are the X,Y pixel position relative to the top left corner of the map. Be aware that using this command can mis-align your hero with the tile-grid, preventing it from walking normally. To position the hero by tile, use the set hero position command.

(what it needs)

A reason to use this versus using "set hero position." It also needs proofreading ("her's" and "mis-align").

And I think this is a good starter list. If anyone would like to tackle the "what it needs" sections, please do.

I'm trying to be a good judge of what needs clarification and what doesn't, but I'm not in everyone's head, so if there's a definition in the first four segments that I didn't list (Declarations, Wait Commands, Suspend and Resume, and Moving Heroes), but should have, please add it to this thread.

Also, a note to James: all instances of the word "heros," including the ones listed in section headers, are spelled wrong. It should be "heroes."

I'll try to add more sections here as the week progresses.
_________________
Progress Report:

The Adventures of Powerstick Man: Extended Edition

Currently Updating: General sweep of the game world and dialogue boxes. Adding extended maps.

Tightfloss Maiden

Currently Updating: Chapter 2

[msw188]

Most likely, the documentation for any command that returns true/false could use the statement "most often used with 'if' commands", together with an example and a link to the 'if' flow control descrirption.

For the 'walk to x' and 'walk to y' commands, a statement like:
"useful when you are not sure where the character is at the time, but are sure where you want him or her to end up"
could be helpful if it was worded better than mine.
Also with these, it should be pointed out that if the character is blocked along the way to the designated coordinate, he or she merely stops, and does not keep trying to get there (as in, if an NPC walked in his path momentarily, he doesn't keep walking after the NPC gets out of the way again).

For check hero wall, a good example might be showing how to use it with an if command when you don't want the player to be able to activate an NPC on the other side of the wall. I guess that might be kind of complicated script-wise, but I really can't think of any simple use for this command.
_________________
My first completed OHR game, Tales of the New World:
http://castleparadox.com/gamelist-display.php?game=161

This website link is for my funk/rock band, Euphonic Brew:
www.euphonicbrew.com

[TMC]

Alright, I've just started on this, changing several of those commands, fixing 'heros', a bug or two, and added an example to puthero. I'll continue later.
_________________
"It is so great it is insanely great."

[Camdog]

Why not makes these changes directly in the wiki, instead of posting about them here?

[Inferior Minion]

[JSH357]

[TMC]

The current xml version happens to already mention that. The wiki version hasn't been updated in over a year (I couldn't get anyone to tell me why not)

Translating from the wiki back to xml format is desired of course (the wiki could possibly be made the master version then). Right now, I can't even find a way to list what plot: articles have been modified by people.
_________________
"It is so great it is insanely great."

[Bob the Hamster]

[Pepsi Ranger]

Dusting off this thread because

a.) I still think the plotscript dictionary needs it, or at least some modified version of it (sort of like how three different companies publish real dictionaries with different wording for each definition), and

b.) I'm still feeling a little on edge about certain flow control items (among other things that I probably don't need to bring up at the moment).

I would love lengthier explanations about unusual commands like "return," "exit return," and so on.

But what I really want to know is how I should use "switch" and "case," and at what point would that even be helpful.

My impression from the example already listed in the plotscript dictionary is that one of several things can happen when a certain number is called, but I have no idea what should separate that from a lengthy line of if/then statements, so logically I have to assume that they're used for some grander purpose.

What I want them to mean is that I can skip an if/then call entirely if another similar condition is already met. For example:

[Bagne]

If we're giving example uses in the PS dictionary, maybe what we really need is a small library of sample scripts, paired with .rpg files to see them in action.
I would imagine that a beginner probably won't be asking questions like "How do I use switch statements?", they'd instead be asking questions like "How do I write a script where a hero can make 5 or more choices?", or "How do I write a script where the dialogue may branch depending on the number of gems the hero found?"

So ... we'd compile a library of examples of typical OHR scripts.
Stuff like:
dudes walking around and talking (already covered by the tutorial's robodance)
calling a script from an item (through a text box)
walking under and over a bridge
special maptile (or walkabout or slice) animations
status bars using slices
stat modification scripts
menu item wrapper scripts (or other clever wrappers)
keypress activated scripts
sample battlescripts (when applicable)
So ... straight forward stuff like that. I would say to keep them simple as possible. Where appropriate, you could link the PS dictionary to these real-life examples in the wiki.

I'd be willing to make a few initial contributions for this kind of thing. I'm sure there's other examples scattered around too ... we just need to gather them together.

Then, for anyone who has figured out a clever programming trick with the OHR, and wishes to share it with the world, there could be a more advanced category. This is where you can put tutorials on platformers, mouse-click adventures, stuff with recursion, or what have you. I'm sure everyone's dying to know how James got the OHR to talk to that python dictionary ... stuff like that.

Again, I would volunteer myself for a few contributions here too.

Btw,
I compiled a small list of PS dictionary clarifications myself and then forgot about it ... I'll see if I can unearth them this evening. I think most of it was to do with clarifying the "who" arguments in commands.
_________________
Working on rain and cloud formation

[Bob the Hamster]

I have updated the descriptions and examples for "return" "exit returning" and "switch". The new file is uploaded to http://hamsterrepublic.com/ohrrpgce/docs/plotdict.xml

In short, yes, switch/case is an alternative for complicated if/then's, and it will probably do just what you want.

I'm not too happy with the way that the plotdictionary is currently managed.

The xml file is cool in theory because it is machine-parseable, but the only program I know of that actually parses it is HamsterWhisper, and I think it does a fairly lousy job of formatting the results.

The xml file is awkward to update, and even though we can export it to the wiki, any edits that people do on the wiki are awkward to include back into the xml file.

[Pepsi Ranger]

Ah, these definitions are much nicer. Thanks. And I like Bagne's idea. It would be nice to have an RPG file dedicated to full on plotscript tutorials that could maybe provide in-game lessons for the advancing plotscripter. Perhaps a modified Robot game that teaches basic 101 stuff, like the moving NPCs scripts that the original tutorial offered, and then lets the student move on to the next, more advanced topic (201, 301, etc.) when he or she feels comfortable using the first topic. The end of the tutorial would of course show us how to make complicated side-scrollers, mouse-controlled adventure games, and Vocabulary Mosaic.

A game like this would be beneficial.

In the meantime, I should probably resume my original idea and pinpoint all the definitions that need better explanation and/or examples. Thanks again for the clarification on these flow control definitions.
_________________
Progress Report:

The Adventures of Powerstick Man: Extended Edition

Currently Updating: General sweep of the game world and dialogue boxes. Adding extended maps.

Tightfloss Maiden

Currently Updating: Chapter 2

[TMC]

The new documentation for switch break and continue is STILL grossly incomplete; it does not mention most of the features of switch. I'll have a go at fixing it up, probably tomorrow.