Content Creation Document
Moderator: Moderators
Content Creation Document
Has there been any hint from Kuju that there will be a definitive document to help those who want to create content for the simulator?
-
KujuClaire
- Official Kuju Representative
- Posts: 8
- Joined: Mon Jul 04, 2005 12:24 pm
- Location: Kuju
- Contact:
-
NeutronIC
- Atomic Systems Team
- Posts: 11085
- Joined: Fri Oct 05, 2001 12:00 am
- Location: E11, London, England
- Contact:
The CCD as described is a detailed technical document with various guidelines (e.g. lods at particular distances for particular items), how the various structures are built for new stock or scenery items and so forth - it's everything that someone contributing more than scenarios and activities will need to understand the sim, a bit like the tech documents that were included with MSTS but perhaps in a less hap-hazard way and going in to more detail in some aspects not just at the nuts and bolts level but also at the standardisation (use as few textures as possible, aim for this size texture, standardised lods (one of my bugbears, I do NOT like to see flying cars appearing a few seconds before the bridge they are on! 
) and so forth).
Take a look at the Auran CCD and do better, but that was on the right tracks
Matt.
) and so forth).Take a look at the Auran CCD and do better, but that was on the right tracks
Matt.
Yes, I fully agree. When you get some documentation for some software, one can usually partition it into a "tutorial" and a "reference". Personally, I prefer a detailed reference manual to a tutorial, even if the learning curve is steeper. Tutorials tend to be incomplete or to cover only the "easy" cases, stopping when it gets interestingNeutronIC wrote:Take a look at the Auran CCD and do better, but that was on the right tracks
Klaus
HiKujuClaire wrote:Hi,
In fact I am currently working on a post release documentation proposal so feel free to tell me what areas you would like to see covered in detail post release and I will see what I can do
Regards
Claire
Animation for - Cab Interiors and Biped - and the successful import of same into KRS.
Biped - I can supply the mesh, textures and mocaps - these are of little use if no clear explanation of correctly setting the required paths is available.
Cab Interiors - mesh, textures and animation of levers is no problem - details of scripting/other required by the software for correct function will be required.
More to follow
Thanks for reading
~A~
-
AndiS
- Very Active Forum Member
- Posts: 6207
- Joined: Fri Sep 23, 2005 4:43 pm
- Location: Jester's cell in ivory tower
- Contact:
I suggest you group it as follows.
Reference manual. This is for the hardcore hackers. Don't say they are only a few because they are the nastiest of your customers.
For each of the (XML) files:
for each of its elements, describe which elements and attributes it can contain,
and for each attribute, spell out which values it can take.
If they are numeric (such as radius of a wheel), don't forget to tell us about permitted units and defaults (and default units). For symbolic values (such as type = carriage, freight ...) list all permitted values with their meaning (and the consequence of using them) plus all values which are reserved for future use. Should there be some numeric ranges of IDs such as in MSTS's track parts, make a plan how to assign these numbers and describe it here.
For each API available to Lua scripting (Signals, what else?) describe each function call (or whatever it is called in Lua) with all its parameters, as described above.
For each process that KRS models internally (physics of engines and wagons, weather, activities of AI drivers & passengers): Describe the process to the smallest detail, followed by a reference of all influence parameters. There is some necessary overlap with the description of the other parts of the reference manual here, but without describing both parameters or data structures on the one hand and internal calculations of KRS on the other hand, no-one will understand it all.
User Manual. Since normal persons will run away screaming if you present them with the reference manual only, you need a description of the tasks which can be done when modelling or configuring or adapting something in KRS. This is best organised in a task specific way. And it is a never ending story.
For starters, you need something like the tutorials available for MSTS. "How to build XYZ". Over the first year or so it should evolve to a collection of white papers or application notes, where external authors describe how they solved a specific problem. E.g., how to implement signalling system X from country Y in period Z. Such in-depth discussions are invaluable time savers for other developers, but it is clear that you (Kuju) cannot supply them yourselves. But you could try to coordinate writers, motivate them, and provide central discussion forums for each of the white papers.
Another complement would be write-ups of the most frequently asked questions, but not in the standard form, but prepared as dummy-proof tutorials which guide people through anything that many people do not understand, whatever that turns out to be – and irrespective of the fact that it may be described somewhere already. This would be created in a reactive way, as a complement to the proactively prepared core of the user manual.
Good practice recommendations. As Matt already mentioned, there should be rule for the soft factors of quality. It would be great to have tools supporting such an analysis, e.g., ShapeViewer shows the polygon count and distance for each LOD and some ratio of polygons and size of object. So to make this type of quality assurance work, we need rules plus tools. And of course everybody's understanding that deviations need not be crimes if well motivated (and only then ).
List of limitations. It is only wise to say frankly what will not work now. For each item, you have three options: Promise it for version 2 (only if you are sure about it, please); Propose a work-around (many things can be done via some extensive scripting, if that is possible); Just say: "sorry, this is beyond the scope" (fair enough for very exotic stuff).
List of special cases. Form a committee for the sick cases. Their task is to find all combinations of parameter values which could give a headache. For each of them, find out if the program crashes and make sure that it does not. Then describe whether such a case is allowed or not and what the consequences are. There is a wide range from not yet implemented feature to plain folly to configuration error.
Examples: 4th rail together with overhead wire; Narrow gauge track inside normal one – sharing one rail or not; Rack railways; Cable railways; horse pulled wagons; Turntables which cannot do a full rotation or slip switches. But also bad configurations such as mismatch of gauge, buffer position, couplers, connectors, speed limitations when composing a consist; Random engine designs; Plants on tracks (rigid or not, big or small).
Of course, items from the list of limitations need not be discussed here, instead the focus is on combinations of existing features which may cause problems. You could see this task force as theoretical beta-testers and indeed their ideas will be input to the QA department. The important point is that you make all these cases public, to show how KRS performs under extreme conditions. And it is always good to actively describing limitations instead of giving the impression that there is a sea of unexplained behaviour. Even more as many of these combinations will be very exotic. But it is nice to know that KRS does not crash under a certain subset of them.
As for the format, you certainly will use some form of hypertext, be it PDF, WinHelp or HTML. Otherwise, you cannot implement the many necessary cross-references efficiently.
Since the whole thing will grow over time (hopefully), a flexible scheme of downloads would be the best form of distribution. Maybe some first part comes as a complete package and the rest comes as supplement. In any case, the reader must have an easy way to determine which information he already has and which needs to be downloaded.
I strongly recommend that you have the documentation beta-tested, as much as the software itself. It costs much less than the software but many a program makes a bad impression because of its sloppy documentation.
And please do not translate the documentation before you have ascertained the assistance of a strong group of native speakers. I always read the English docu whenever I can get it because it is so difficult to figure out what people might have thought of when coming up with a certain term.
Reference manual. This is for the hardcore hackers. Don't say they are only a few because they are the nastiest of your customers.
For each of the (XML) files:
for each of its elements, describe which elements and attributes it can contain,
and for each attribute, spell out which values it can take.
If they are numeric (such as radius of a wheel), don't forget to tell us about permitted units and defaults (and default units). For symbolic values (such as type = carriage, freight ...) list all permitted values with their meaning (and the consequence of using them) plus all values which are reserved for future use. Should there be some numeric ranges of IDs such as in MSTS's track parts, make a plan how to assign these numbers and describe it here.
For each API available to Lua scripting (Signals, what else?) describe each function call (or whatever it is called in Lua) with all its parameters, as described above.
For each process that KRS models internally (physics of engines and wagons, weather, activities of AI drivers & passengers): Describe the process to the smallest detail, followed by a reference of all influence parameters. There is some necessary overlap with the description of the other parts of the reference manual here, but without describing both parameters or data structures on the one hand and internal calculations of KRS on the other hand, no-one will understand it all.
User Manual. Since normal persons will run away screaming if you present them with the reference manual only, you need a description of the tasks which can be done when modelling or configuring or adapting something in KRS. This is best organised in a task specific way. And it is a never ending story.
For starters, you need something like the tutorials available for MSTS. "How to build XYZ". Over the first year or so it should evolve to a collection of white papers or application notes, where external authors describe how they solved a specific problem. E.g., how to implement signalling system X from country Y in period Z. Such in-depth discussions are invaluable time savers for other developers, but it is clear that you (Kuju) cannot supply them yourselves. But you could try to coordinate writers, motivate them, and provide central discussion forums for each of the white papers.
Another complement would be write-ups of the most frequently asked questions, but not in the standard form, but prepared as dummy-proof tutorials which guide people through anything that many people do not understand, whatever that turns out to be – and irrespective of the fact that it may be described somewhere already. This would be created in a reactive way, as a complement to the proactively prepared core of the user manual.
Good practice recommendations. As Matt already mentioned, there should be rule for the soft factors of quality. It would be great to have tools supporting such an analysis, e.g., ShapeViewer shows the polygon count and distance for each LOD and some ratio of polygons and size of object. So to make this type of quality assurance work, we need rules plus tools. And of course everybody's understanding that deviations need not be crimes if well motivated (and only then
).List of limitations. It is only wise to say frankly what will not work now. For each item, you have three options: Promise it for version 2 (only if you are sure about it, please); Propose a work-around (many things can be done via some extensive scripting, if that is possible); Just say: "sorry, this is beyond the scope" (fair enough for very exotic stuff).
List of special cases. Form a committee for the sick cases. Their task is to find all combinations of parameter values which could give a headache. For each of them, find out if the program crashes and make sure that it does not. Then describe whether such a case is allowed or not and what the consequences are. There is a wide range from not yet implemented feature to plain folly to configuration error.
Examples: 4th rail together with overhead wire; Narrow gauge track inside normal one – sharing one rail or not; Rack railways; Cable railways; horse pulled wagons; Turntables which cannot do a full rotation or slip switches. But also bad configurations such as mismatch of gauge, buffer position, couplers, connectors, speed limitations when composing a consist; Random engine designs; Plants on tracks (rigid or not, big or small).
Of course, items from the list of limitations need not be discussed here, instead the focus is on combinations of existing features which may cause problems. You could see this task force as theoretical beta-testers and indeed their ideas will be input to the QA department. The important point is that you make all these cases public, to show how KRS performs under extreme conditions. And it is always good to actively describing limitations instead of giving the impression that there is a sea of unexplained behaviour. Even more as many of these combinations will be very exotic. But it is nice to know that KRS does not crash under a certain subset of them.
As for the format, you certainly will use some form of hypertext, be it PDF, WinHelp or HTML. Otherwise, you cannot implement the many necessary cross-references efficiently.
Since the whole thing will grow over time (hopefully), a flexible scheme of downloads would be the best form of distribution. Maybe some first part comes as a complete package and the rest comes as supplement. In any case, the reader must have an easy way to determine which information he already has and which needs to be downloaded.
I strongly recommend that you have the documentation beta-tested, as much as the software itself. It costs much less than the software but many a program makes a bad impression because of its sloppy documentation.
And please do not translate the documentation before you have ascertained the assistance of a strong group of native speakers. I always read the English docu whenever I can get it because it is so difficult to figure out what people might have thought of when coming up with a certain term.
-
AndiS
- Very Active Forum Member
- Posts: 6207
- Joined: Fri Sep 23, 2005 4:43 pm
- Location: Jester's cell in ivory tower
- Contact:
Sorry to contradict you here a bit, Klaus.
Btw. the Schema files must be included with the initial KRS distribution, otherwise any XML editor will refuse to work on the XML data files.
A formal grammar would be a first starting point. It gives you a check list of what you need to describe. What I demanded is a full explanation of every possible value, not just a list of possible values.KlausM wrote:A formal grammer like XML Schema files (see W3C) would be nice.For each of the (XML) files:
Btw. the Schema files must be included with the initial KRS distribution, otherwise any XML editor will refuse to work on the XML data files.
Sorry for becoming off-topic, but XML files do not need to have Schema files for being correct. They don't need to have a grammar at all (they only need to be "well-formed"). This applies to XML files using Namespaces as well. If your editor refuses to edit such XML files, it is simply buggy. So Kuju don't need to include them in distribution. Maybe they use Schema validation internally while loading the files, then the software surely needs the files somewhere, but that's a different story.
And of course, Schema files do not substitute a good documentation. I didn't mean that. So I added a plus sign to my message.
Klaus
And of course, Schema files do not substitute a good documentation. I didn't mean that. So I added a plus sign to my message.
Klaus
-
johnarran
- Established Forum Member
- Posts: 303
- Joined: Sun Dec 30, 2001 12:00 am
- Location: Swansea, UK
I think some documentation on terrain generation and forming would be essential. Anyone considering some serious route building is going to need it. I remember that in MSTS DEM imports were a no go for anyone in the UK because of cost and we had to rely on some excellent 3rd party software like TSTerraform. What tools would we use in KRS for creating accurate landscape?
John
John
-
ForburyLion
- Very Active Forum Member
- Posts: 1225
- Joined: Fri Jun 14, 2002 7:30 pm
- Location: Reading
-
GenmaSaotome
- Been on the forums for a while
- Posts: 102
- Joined: Sat May 13, 2006 5:12 pm
- Location: Silicon Valley
When you get around to doing a North American edition:
* do not assume the technical jargon will be the same... have somebody on this side of the pond review it all.
* If you can reveal the actual formulas used for things like friction, brake performance, and steam locomotive tractive force at speed, please do so.
* Please document the range of acceptable values.
* A designer commentary would be useful -- what was the perceived objective for feature XYZ, what was tried, why set this or that proposed solution were aside, and what the final decision means for content creation. Things like that.
* do not assume the technical jargon will be the same... have somebody on this side of the pond review it all.
* If you can reveal the actual formulas used for things like friction, brake performance, and steam locomotive tractive force at speed, please do so.
* Please document the range of acceptable values.
* A designer commentary would be useful -- what was the perceived objective for feature XYZ, what was tried, why set this or that proposed solution were aside, and what the final decision means for content creation. Things like that.