Data File Author Feedback Request on AB3

[Russell]

Originally Posted by TheDaR

The other thing I've thought of is better error messages from the script compiler. 'Invalid use of reserved word in script' isn't a very helpful in terms of knowing what to fix. Even just adding the token which caused the error to that message would help a lot (Invalid use of reserved word "parent" in script) in narrowing down which context transition you messed up.

Now THAT is a great idea! I'd love to see this too.

[Russell]

I'd like to be able to italicize an option (using a name override) for some units, but have the option and description only appear once in the footnotes...

I guess what I'm asking for is that if an option name override is identical to the non-override name, except for the encoding, that it be treated as the exact same option in the footnotes.

[Colen]

At 07:06 PM 6/7/2005 -0400, you wrote:

>I'd like to be able to italicize an option (using a name override) for
>some units, but have the option and description only appear once in the
>footnotes...
>
>I guess what I'm asking for is that if an option name override is
>identical to the non-override name, except for the encoding, that it be
>treated as the exact same option in the footnotes.


This should already be happening? I thought we'd added this in v3.0b.

[deathlynx]

For the docs, maybe an order of action list which spells out specifically what happens when? For example (please don't correct this as I'm just BSing the list) Pre Link Global, Member, Cost, Post Link Global...That way we have a very quick and easy list to double check where priority happens...

[Russell]

Originally Posted by Colen

>I guess what I'm asking for is that if an option name override is
>identical to the non-override name, except for the encoding, that it be
>treated as the exact same option in the footnotes.
This should already be happening? I thought we'd added this in v3.0b.

Hmm... Seems I didn't take enough notice when 3.0b came out... scrap that last request!
ops: Sorry!

[rob]

At 10:14 PM 6/7/2005 -0400, you wrote:
>For the docs, maybe an order of action list which spells out specifically
>what happens when? For example (please don't correct this as I'm just
>BSing the list) Pre Link Global, Member, Cost, Post Link Global...That way
>we have a very quick and easy list to double check where priority happens...

I hereby point you to the "Concepts" chapter of the existing docs
(kit_concepts.htm). Scroll down to near the bottom and you'll find the
topic "Evaluation Sequence". This walks you through the exact sequence in
which everything gets evaluated.

I realize that the documentation is lacking a lot of "why" and "how"
information, but it's not lacking on the crunchy bits. :-P

-Rob

---------------------------------------------------------------------------
Rob Bowes (rob@wolflair.com) (408) 927-9880
Lone Wolf Development www.wolflair.com

[rob]

At 02:08 PM 6/7/2005 -0400, you wrote:

I've got some of these in my list. But I'd really love a list of topics
that YOU want to see addressed, since my list probably doesn't match your
list exactly.

Off the top of my head:

• Naming conventions to make tracking options/entities easier
• When to use costs on options versus on entities
• Which scripts are best for calculating/testing various common things, when various ones can do the same thing (eval vs live, sizelimit vs postlink, etc)

Basically, some philisophical discussion of what the program's authors would do when confronted with various situations, knowing the program inside and out.

Hmmm. For the topics you list above, I'm not exactly sure what I could write. These three areas are SO subjective and SO dependent on the situation that they pretty much defy a deefinitive answer.

I'm including some suggestions on the selection of unique ids, but naming is such a personal thing. Something that is self-evident to one person might make no sense at all to someone else. The real key to naming is consistency. As soon as someone understands the rules you've used for naming, regardless of how strange those rules might seem, all the names start to make sense. Beyond that, I don't know what I could say in support of making the "tracking of names easier".

Whether to apply costs to options or entities is a very situational decision. I'm including some discussion on this, but the bottom line is really "it depends on the situation". I'll see what I can add regarding when it's better to use one approach over the other.

Deciding which script approach to use in a given situation is another classic "it depends". I'm including some suggestions, but each situation demands an independent evaluation. It also depends on what other factors are involved that need to be accommodated, since those can influence the solution used.

I guess the point I'm trying to make is that there are numerous ways to solve most problems in AB, and there will rarely be a definitive "right" way that can be identified. There will simply be "better" and "worse" solutions, but often times one solution might be better than another in some respects and worse in other respects. While I'll do my best to offer a lot of suggestions in the docs, don't get your hopes up that it will provide a definitive answer to everything. :-)

If you're going to be at GenCon this summer, definitely plan to go to our workshop on advanced AB data file writing. The entire focus of the workshop will be analyzing real situations and figuring out what works best. We'll also be available at the booth throughout the show to discuss solutions. And you can always post specific situations here. We'll be happy to offer suggestions if you want them. Just make sure to provide us with sufficient details about the game mechanics you're trying to model (since we aren't experts on every game).

Viewing (especially as a tool tip, something AB does very well overall) would be a very strong start.

I'd also be fine if following any unresolved links just popped up a dialog that said something like 'This link doesn't resolve in this file, would you like to (open another file) (create an option/entity in this file) (cancel)'. Those three options would pretty much solve 90% of the use cases I can think of; namely either wanting to switch to the link in the current datafile (most of the time), create a new option or entity as appropriate (most of the rest of the time), and on the very rare cases go to another file.

That's an excellent suggestion. Something concrete that we can probably do in a manageable chunk of time for a release. That's exactly the type of suggestion I was looking for!

The other thing I've thought of is better error messages from the script compiler. 'Invalid use of reserved word in script' isn't a very helpful in terms of knowing what to fix. Even just adding the token which caused the error to that message would help a lot (Invalid use of reserved word "parent" in script) in narrowing down which context transition you messed up.

Unfortunately, given the way the parser is written, this is a LOT harder than it sounds. Just adding something that seems simple like this would probably take me DAYS to put into place. It's all due to the parser design, which makes some things really convenient but others (like detailed error reporting) a real pain.

That being said, this is definitely something I want to improve upon. I'm just not sure how soon I can reasonably get it done.

-Rob

---------------------------------------------------------------------------
Rob Bowes (rob@wolflair.com)******************************** (408) 927-9880
Lone Wolf Development************************************* www.wolflair.com

[TheDaR]

Originally Posted by rob

At 02:08 PM 6/7/2005 -0400, you wrote:
Hmmm. For the topics you list above, I'm not exactly sure what I could write. These three areas are SO subjective and SO dependent on the situation that they pretty much defy a deefinitive answer.

A discussion of what the trade-offs are would be fine. Basically, like with the Perl programming languages, when you have a tool like Army Builder which is so very flexible, it can sometimes be hard to get enough of a mental grasp of what the trade-offs even are. A few paragraphs on the merits of each would provide someone with enough foundation to be able to make a semi-informed decision about which is the best option for them.

Originally Posted by rob

If you're going to be at GenCon this summer, definitely plan to go to our workshop on advanced AB data file writing. The entire focus of the workshop will be analyzing real situations and figuring out what works best. We'll also be available at the booth throughout the show to discuss solutions. And you can always post specific situations here. We'll be happy to offer suggestions if you want them. Just make sure to provide us with sufficient details about the game mechanics you're trying to model (since we aren't experts on every game).

I'd love to be at GenCon, sadly it's not in the time or money budget this summer.

That said, you guys have been very good about answering questions here, certainly.

Originally Posted by rob

Unfortunately, given the way the parser is written, this is a LOT harder than it sounds. Just adding something that seems simple like this would probably take me DAYS to put into place. It's all due to the parser design, which makes some things really convenient but others (like detailed error reporting) a real pain.

That being said, this is definitely something I want to improve upon. I'm just not sure how soon I can reasonably get it done.

I don't know if you built your parser and interpreter with yacc/bison, but if you did, even turning on YYDEBUG would be a big help.

That said, in the long run, I'd like to see a script interpreter which was a little more 'standard' and powerful. There are a couple of really good options out there that are fairly easy to integrate and from my (still limited) perspective seem like they could fit into the AB datamodel pretty well. Lua is the first one that springs to mind, as it has some features that make it absolutely ideal for building an embedded scripting language which extends an application's datamodel. Python could also work well. Hell, I'd settle for VBA or something similar, given AB is pretty strictly a Windows app.

But that's obviously a ways down the road, if it gets done at all.

-DaR

[deathlynx]

Ok, so I think I've discovered one of my biggest problems with the docs...I'm able to speak English and that's about it :P ...
I found the list but it's things like "Invoke any Evalonce option script, applying all changes" that leave me scratching my head in confusion...While I understand that high level programmers are the primary targets for creating Data files there are some of us who only have more basic levels of programming in our backgrounds...

Oh, and the other big problem is confusion in finding things in the docs...I think it needs a better index...I wouldn't have even begun to guess where to look for an evaluation sequence...Also now that I've found it, the ability to cross refference an index for the word "Evalonce" would probably go a long ways to solving my technical deficiencies...

[rob]

You'll find the details of all scripts defined in the chapter entitled
"Script API" (kit_api.htm). You can access all the script-related material
via the "Scripting" link on the main page of the Kit manual.

Unfortunately, the EvalOnce script was dropped near the end of development
on V3.0, and I forgot to remove it from the evaluation sequence. There is
only one Evaluation script now for options. I'll get that fixed.

I guess I don't understand what's confusing about the statement "Invoke
Script X once, applying any changes". That translates to the following in
my mind: "ScriptX gets invoked and any changes it triggers are applied".
That's all that gets done in the engine, so what more detail do you want on
this?

With the documentation overhaul, I'm going to do a better job of getting
links into place. With regards to an index, I have no idea what the best
solution is. Creating and maintaining an index by hand is prohibitive. If
someone wants to identify a tool that will take a set of webpages and
generate a unified index for them, I'd love to hear about it. Beyond that,
better cross-links between pages may have to suffice.

-Rob

At 06:50 PM 6/8/2005 -0400, you wrote:

>Ok, so I think I've discovered one of my biggest problems with the
>docs...I'm able to speak English and that's about it ...
>I found the list but it's things like "Invoke any Evalonce option script,
>applying all changes" that leave me scratching my head in
>confusion...While I understand that high level programmers are the primary
>targets for creating Data files there are some of us who only have more
>basic levels of programming in our backgrounds...
>
>Oh, and the other big problem is confusion in finding things in the
>docs...I think it needs a better index...I wouldn't have even begun to
>guess where to look for an evaluation sequence...Also now that I've found
>it, the ability to cross refference an index for the word "Evalonce" would
>probably go a long ways to solving my technical deficiencies...


---------------------------------------------------------------------------
Rob Bowes (rob@wolflair.com) (408) 927-9880
Lone Wolf Development www.wolflair.com