Parts of the ACR2 uploaded to repository

[Ronan]

I uploaded these a few days ago, and I'm hoping for some comments. Mostly its a general overview of the architecture I'd like to see, with implementations of key systems or things I just felt like doing. So please focus your critisism on overall design and structure, but any specific problems spotted are also welcomed.

Some of the files were written before I had made some decisions on other systems, and things may not fit together that well for this reason. Please ignore this, as I didn't have enough time to go through it all before I left town, and writting code (even if junked) is one of the things which helps me think through architecture, potential problems, etc.

Thanks.

[indio]

It's good to see work being done.

http://www.thesavagefrontier.net/Uploads/DMC001/acr.htm

Check that link out Ronan. Cipher and I with Wynna's help are trying to decide on a structure for the compendium that you might find interesting. Should we match structures?

[Ronan]

I don't think its terribly important for anything in the DM manual to follow the architecture of the ACR, but when we get the wiki up, I'll certainly have things to add.

[indio]

It's not so much how it goes into the dm manual, but the Basemod itself. Might be useful to keep it consistent. What do you think cipher?

[ç i p h é r]

This isn't an [software] architectural issue but really an organizational one. The underlying principles are essentially the same; to make it easy to find information you are looking for. So, I can't help but think it would make sense to organize our documents in much the same way as we've organized our content. I liken it to 'context specific' help.

But I'm wise enough to realize that there is always more than one way to skin a cat. We needn't be restricted by any organizational preferences from one system to the other if it impedes access and/or clarity.

Let me rearrange the repository (if I'm permitted to) and we can take it from there. I made the changes on my end, but held off committing them to the repository. I'll commit them tonight so we can move forward.

[Ronan]

This isn't an [software] architectural issue but really an organizational one. The underlying principles are essentially the same; to make it easy to find information you are looking for. So, I can't help but think it would make sense to organize our documents in much the same way as we've organized our content. I liken it to 'context specific' help.

Agreed, and I was going to add a ALFA Tech Team article to the wiki, when it gets up. I just didn't think those sorts of things belonged in the DM manual, with the exception of documentation on how DMs use and interact with the ACR. While other parts of the basemod need to be more detailed to DMs (creatures, items, etc) the ACR does not, IMO.

I'd prefer to leave the details on the inner-workings of it to a developer's manual, with only the needed information given to builders and DMs. They have far too much to learn and read through as it is, IMO. We were planning on adding builder's, DM's, and developer's manuals to the wiki, correct? I'd prefer to just let the tech guys tackle the dev's manual, and if you feel it necissary to link off the resulting component-specific articles for the DM or builder's manual, then go ahead.

However, I'm really big on jamming documentation into my tools and code(after all, its just as easy to type a help doc inside the DM wand as it is in a wiki), so I'm hoping most DMs will find the majority of component-specific documentation already present in-game as well as in the wiki.

But I don't think we should document any thing in more places than its needed, that can result in outdated documentation. I'm not sure internal ACR information is needed outside of ACR developement, which would mean that documentation could reside only in the code itself and all would be well.

[indio]

I think we're all on the same page then pretty much. The DMC isn't, conceptually at least, just the DM Manual. A section of it will become the DM Manual. Currently its primary purpose, as I see it, is the documenting and conceptual structuring of the Basemod...to wit, how do we actually organise the full content of the Basemod, ACR, Palettes, and the rest.

The point ultimately is that we might be better served if the structure of the DMC matched the content being added to sourceforge. I'm more than happy to change the DMC to match what's being added to sourceforge, so cipher, let me know how you want to proceed.

[peterdin]

Allow me to throw in my ideas/comments about this:
I'd like to disagree with cipher on the difference between organizational and architectural issue.
Many times you see the architecture of a system being refelected in the (project) organization (or vice versa )
This makes the management of the project a lot easier as repsonisbilities can clearly be allocated to both the architecture AND the project.
So I agree with cipher that it would make sense to "organize our documents in much the same way as we've organized our content".

Furhter putting the source of information on one place is alwasy a very good idea.
If needed this information can be extracted from this source to be displayed in several places (wiki, on-line in game, DM manual etc etc..)
So it would be a goo idea to check on tooling that can generate help files etc from our code.
I know about tools like ndoc or doxygen that can do that job for you, but I don't know if they work on our repository.

I'll check on this and the repository structurre and get back with remarks

[ç i p h é r]

Thanks for your comments peter.

To clarify, by architecture I mean the actual software design (the code framework) and by organization I mean the directory/repository structure. The latter would certainly have no influence on the former but the former could certainly have influence on the latter as you rightly imply.

I'd be interested in your findings on documentation tools that will work with NWScript. Something that can aggregate comments and function prototypes, and compile a data dictionary for each system would obviously be an immense time savings.

Also, I committed the changes to the repository. To anyone reading, please do not commit compiled source files to the repository (.ncs files). They are unnecessary. I kept the "nwn2" directory alone as it seems more of a temp dev area that Ronan is using for the time being, but please realize that while it certainly is possible to delete and move content (as evidenced by the changes I made), making wholesale changes to the repository structure is a ROYAL pain and best avoided. So, I'd appreciate if we progress in as orderly a manner as possible. In other words, please let me know what you plan to commit before you commit something new.

Thanks everyone.

[Ronan]

The point ultimately is that we might be better served if the structure of the DMC matched the content being added to sourceforge. I'm more than happy to change the DMC to match what's being added to sourceforge, so cipher, let me know how you want to proceed.

At this stage, I'd say your probably wasting your time. Currently we've only got scripts, and I'd prefer to keep any documentation on scripts in the scripts themselves. The people only people who need to read docs on them have access to them, and I'd much prefer to keep all that documentation in one spot (and it needs to be in the code, regardless of where ever else it is).

Once we start getting things like palletes, creatures, items, and other things which cannot contain their own documentation (since they are not made up of text, as scripts are) I'd say this will be of more use.

Of course your welcome to do whatever you want, but its hard enough to get volunteer coders to document changes and things properly when they only have one spot to do it in, let alone two or more.

Agreed with peterdin and Cipher, something javadoc-ish to compile documentation from our code would be great.

Cipher, how did you want .ncs files added to the hak(updater) then? When Baalster alters a hak, its enourmously easier for him to do so with only the changed files (though this may be less of an issue if we move all script files to the smaller 2da hak). Naturally if all he has to do is update his local SVN repository and run the hakupdater on it, things are much easier than if he had to compile .ncs files himself in the toolset, then extract them from a mod (I haven't had any luck with the CLI compiler, but I've not played with it much). Of course, we could always give him the changed files manually, but that seems like wasted effort with a chance of human error when SVN does that for us.

[indio]

The point ultimately is that we might be better served if the structure of the DMC matched the content being added to sourceforge. I'm more than happy to change the DMC to match what's being added to sourceforge, so cipher, let me know how you want to proceed.

At this stage, I'd say your probably wasting your time. Currently we've only got scripts, and I'd prefer to keep any documentation on scripts in the scripts themselves. The people only people who need to read docs on them have access to them, and I'd much prefer to keep all that documentation in one spot (and it needs to be in the code, regardless of where ever else it is).

Wouldn't be the first time. Again, the DMC is an opportunity to see the Basemod's overall structure, a chance to see if we've left anything out, and moreover, a chance to develop a consistent framework for building. I don't think the DMC will ever contain the documentation of the scripts. I thought you were asking for feedback on the structure of your additions, which is why I thought taking a look at an existing structure might be useful.

Of course your welcome to do whatever you want, but its hard enough to get volunteer coders to document changes and things properly when they only have one spot to do it in, let alone two or more.

Just to reiterate, we're talking structure of the souceforge repository, or so I thought. Should it become useful to add the documentation to the DMC then naturally I'd do it given I've access to the courceforge project and am quite happy to. Doesn't take long at all.

[ç i p h é r]

Cipher, how did you want .ncs files added to the hak(updater) then? When Baalster alters a hak, its enourmously easier for him to do so with only the changed files (though this may be less of an issue if we move all script files to the smaller 2da hak). Naturally if all he has to do is update his local SVN repository and run the hakupdater on it, things are much easier than if he had to compile .ncs files himself in the toolset, then extract them from a mod (I haven't had any luck with the CLI compiler, but I've not played with it much). Of course, we could always give him the changed files manually, but that seems like wasted effort with a chance of human error when SVN does that for us.

What's the current update process for the source HAKs? I presume files are exchanged manually and Baalster simply updates the haks on his end. With the SVN repository, that's obviously not necessary as the latest hak content can be obtained with a simple "SVN update" (sync). If we can get the command line compiler working, can we automate the whole release process (ie command line SVN update, hak unpacking, content comparisons, script recompiles, and hak repacking)? It would be easy to do with a robust shell, but I don't know much about the current environment to jump to any conclusions. If we can't get the command line compiler working, then I've no objections to storing hak'd .ncs files in the repository for simplicity.

For NWN2, I expect our HAK sizes (if they are still supported) to be dramatically smaller given that a low budget modeling tool won't be available to the community. Scripts, blueprints, 2das, music, and portraits may be the extent of hak'd content (at least initially).

[ç i p h é r]

Just to clarify the documentation issue, Indio is referring to high level feature specifications and any related documentation (like possibly the visual models). These describe how the systems work and are not strictly developer docs. Everyone who scripts, builds, administers, or DMs should have high level knowledge of the systems in the game. The forum is not the best place for such documentation and in lieu of something better, I've asked Indio to maintain this in the DMC he put forth and recommended we organize the specs in much the same way we organize the repository. It'll be far easier to correlate the two that way if nothing else. One aggravating factor however is the ease with which the information can be accessed in the DMC, which may force us to organize independently of the repository. This may largely be a subjective issue however.

The low level documentation found in scripts that describe the software implementation is what Ronan is referring to, which need not clutter nor be bundled in with any DM manual. These are only relevant to those who script. With any luck, there will be a tool out there that can auto generate these documents for us.

[peterdin]

well that's a lot of text.
So for my understanding:

- overall description (architecture) in DMC
- lowl level doc in the scripts itself
- if possible: doc extracted from scripts in HTML or some other form

[ç i p h é r]

Nice summation.

Is everyone ok with this approach? If there are objections or concerns, please state them.