Cleannup @ Wikibooks + Call experiments

[Xoid]

NOTICE:

 

I'm organising a cleanup of: Blades of Avernum Script Reference . Anyone who feels like participating can. Please see Talk:Blades of Avernum Script Reference for more information.

[Kelandon]

After I finish Exodus, I'm planning to completely rewrite the docs, but that probably won't be until summer, and what I'm doing won't start in the Wiki.

 

So you have my moral support, although I don't know that I'm going to be contributing much at this time.

[Xoid]

By the dictatorial powers invested in me, I proclaim that this endeavour be known as "the great editing", by future generations.

 

(Hey, since the only person to even bother commenting on this was Kelandon, and since I'm likely going to be doing most of this myself, a little bit of hubris seems appropriate.)

 

I've decided to recreate the documentation, in it's entirety, under the AvernumScript name.

 

God forbid that I actually get anywhere with this today, but a little bit has been done so far (mostly in the appendix), but it's 4:52AM and I'm getting tired.

 

God forbid that I decide to do this at normal hours.

 

God forbid that, as a staunch atheist, I use the phrase God forbid too much. Oops, too late.

 

EDIT 1:

I've done a little 'testing' into what certain calls return, specifically, the calls that didn't list anything, not even void. Three of them act like calls that return voids, two of them do not.

 

To learn how a function that returns the void data type acts, I experimented with about 5 calls that the documentation claims return the void data type.

 

(The two had something to do with strings, IIRC. I'll provide more accurate information when I'm not so tired.)

 

EDIT 2:

Corrected some grammatical errors and spelling mistakes.

[Dintiradan]

(Because you and Kel seem a little lonely in this topic.)

 

The Script Reference had been kind to me so far. If I find any errors in it, I'll let you know. How exactly will you rewrite the Docs? Novice-friendly, or concise for the power-user?

 

Anyway, between creating a scenario, finishing A4, and maybe creating "AvernumScript Light" (an auto-scripting tool for novices I've been toying with), I don't think I'll be able to be of much aid.

 

EDIT: By CPeters:

Quote:

(The two had something to do with strings, IIRC. I'll provide more accurate information when I'm not so tured.)

It shows.

 

--------------------

IF I EVER BECOME AN EVIL OVERLORD:

If the hero runs up to my roof, I will not run up after him and struggle with him in an attempt to push him over the edge. I will also not engage him at the edge of a cliff. (In the middle of a rope-bridge over a river of molten lava is not even worth considering.)

[Kelandon]

As far as I'm concerned, the more information, the better. I have to do far too many experiments just to figure out how calls work before I can use them.

[Xoid]

There is something to be said for brevity, but only when it's called for. I'm trying to keep things clear, concise and consistent. I'll put detailed descriptions when they are called for.

 

If anyone thinks that examples for every call would be of great assistance, then I'll add one.

 

It's only a call to the example template, and a sentence or two, after all. The main issue would be: is it necessary to have an example for every call?

 

About the calls that I experimented with:

 

Acted like functions that return the void data type:

• reset_dialog()
• reset_dialog_preset_options(short dialog_options)
• turn_on_debug_mode()

 

Acted differently to all other functions so far, except themselves. (I'm calling this the "unknown" data type):

• print_big_str(string str,short num_to_print,string str2)
• print_big_str_num(string str,short num_to_print,string str2,short color)

 

My thoughts on these calls:

From my growing knowledge of C, functions that work with strings are... different to all other functions, generally doing wierd stuff.

 

the data type returned here, were Avernum written in any other language than C, would seem to be the string data type. In all likelyhood, it is probably not.

 

Admittedly, Jeff may be using a flavour of C that I am unfamiliar with, which would be most of them. On top of that, I'm far from proficient in C, it's way outside of my comfort zone at this point in time.

 

Of course, if one were willing to do what is an illegal act, you could decompile Blades of Avernum to determine (approximately, anyway) what is going on.

 

A couple of legal alternative to this would be:

• Exhaustive testing.
• Ask Jeff.

[Kelandon]

It probably would not be hard to dig up with examples of every call. Ideally, I'd cite where the examples are found (t7Tiger.txt in Canopy, for instance), so that they can be seen in context.

 

In what way are print_big_str and print_big_str_num different from void calls?

[Xoid]

Quote:

Taken from my write up on data types:
The void data type has been partially verified. Using the functions such as void print_num(short num) where short calls a function that also returns void, BoA will display the error message "Empty expression in line %d". %d, for those unfamiliar with programming, is simply a placeholder an integer.

The calls that I suspect don't return void... when used as the argument for the print_num() function, I get the error message "Bad term in expression in line %d."

[Kelandon]

Huh. I'm not sure that this distinction matters terribly much, because those two calls will still always return errors when used as arguments for other calls, as far as I know. Even if the errors are different, they're still errors, and the difference can't be used to do anything.

 

But then, there may be some importance to this that I can't see right away.

[Fort]

That is an interesting finding, but since this mysterious return type results in an error message makes it is ruinous for gameplay atmosphere.

 

I took a quick look at the wikibook for the calls, and it seems to function perfectly as a quick reference page, which I take to be its original purpose. But since it would almost be trivial for a group of people familiar with scripts to write clear descriptions and provide discerning examples for each, improving it is a matter of "Why not?".

 

Providing references to scripts would be great for very complex or unique scripting procedures, but I think that high quality examples will suffice for most. There are numerous little details about the operation of the scripting engine that could be written out, though. For example, the order in which different scripts, such as the town script, scenario script, creature script, run. Of course, bugs should be pointed out.

 

I am going to look at the discussion on the site now to make sure that I have not just repeated what people have been saying...