2D Blog Day
by Michael Perry · 09/06/2012 (9:22 am) · 40 comments
2D Blogs: Documentation
Kickoff
Greetings everyone. It's another 2D blog day! When time allows, someone on the 2D team will post a blog or resource related to Torque 2D and/or iTorque 2D. The majority of the posts will come from myself, but don't be shocked if someone else takes over for me from time to time.Last time, I posted a very brief status update to let everyone know we are still working. We're quite busy at GarageGames, so frequent updates are difficult to justify. In my last blog, general requirements for the T2D technology were listed in a high-level fashion. We had a short Q&A session in the comments, which I encourage in all of the blogs I post. This week I'll be talking about documentation for the engine. First, here's the "let's cover our bacon section":
FULL DISLOSURE
Do not take the content from these blogs as law. I'm never going to say "this will be in x.x version" or "this is ready to be used right now". There's going to be a lot of R&D discussion. I might even post a discussion I had with Melv that ended up being scrapped. It might be useful for you to understand how we communicate internally, or amusing to see the mad scientists we really are. I will not post timelines. I will not post release dates. I will not commit the team to something we cannot deliver on.
Docs, docs, docs
Veteran community members know I got my start at GarageGames by writing documentation. For the first half of my GG tenure, that's all I focused on. As time went by, I slowly earned my spot as a full time engineer on the team. As awesome as Torque 3D is, my true passion is for 2D technology. It's no secret that the T2D docs have been neglected. We did our best to cleanup the formatting and fix tutorial bugs, but there is a major gap between content and quality when you compare the product to Torque 3D's docs.With iTorque 2D 1.5, I scrapped a huge chunk of the old TGB docs. The basics of iT2D's docs were written from scratch. All in all, I think they are a solid "getting started" reference. Under the mindset of "bad docs are worse than no docs", we did not attempt to fix the TGB docs to work with iT2D. It was the right move to just delete content, with the hopes of replacing them in the future.
This brings us to the future Torque 2D product, which is actually a combination of T2D and iT2D. Before I post the next sentence, I must urge you all to NOT PANIC. Ok, deep breaths. With the exception of core systems, there is absolutely no documentation for the future Torque 2D. Wait for it. YET.
Ok, sorry. That's enough word teasing. The reality is that I can not identify a single paragraph or image from the older docs that will be useful in the future Torque 2D. I'm not exaggerating. All of the classes have been renamed. The editors have a completely different appearance. The folder structure was drastically changed to work with the new module system.
The Bad
The obvious bad part is that we have to write a whole new set of docs. Speaking from my own experience with Torque 3D, that is no small task. In fact, is is monumental and impossible for a single person to accomplish. Just think about all that goes into good docs:- Overview of the editors
- Engine overview
- Scripting manual
- 3rd party systems
- Class reference
- Tutorials
- Reference images
The Good
Starting from scratch has its benefits. We are afforded choices we did not have in the past. We can pick our format, the location of the docs, the time to implement systems that can auto-generate docs (like T3D), the delivery, embedding into the editor, and so on. These are all special treats I've wanted for a while. For a weirdo like me, I'm actually excited to have a clean slate and no baggage. It's very freeing.Additionally, there is no longer an individual docs guy. We still have Geoff, who took over my spot as the lead for documentation. Melv and I both have experience with creating great docs for T2D. We have been forcing our engineers to comment all of their behaviors and script code, making it easier to understand what is going on if you want to reuse our code.
Then there are the support troops. Yup, that's you all. We are going to set up a system for you to provide documentation. What's that you say? That's our job? What do you get out of it? Well, with that mentality you can go ahead and skip the rest of this section and go about your day. For the rest of you, we do have treats. Helping us create new documentation will yield rewards. I'd like your opinions on what is worth the effort, but I already have a few suggestions myself:
- Early access to updates
- Free software
- Your name in the official engine credits
- The rewarding feeling of knowing something you have created is used by hundreds, thousands of people
Wrap Up
Alright, so this blog did not contain fancy images or a tech update. Honestly, I'm ok with that. I can talk about documentation all day. I may be an engineer now, but I still believe documentation is the most important feature of an engine. You can disagree, but I have seen many surveys, blogs, and rants that would be on my side.Next time, I will get into more technical topics of what's going on in Torque 2D. If you are the impatient type, feel free to ask whatever you want in this blog's comment section. Thanks for reading!
About the author
Programmer.
#2
That is part of the direction moving forward that we are figuring out. We need to work with the community to find out how best to continue down the documentation path.
09/06/2012 (9:53 am)
@LuisThat is part of the direction moving forward that we are figuring out. We need to work with the community to find out how best to continue down the documentation path.
#3
The entire asset system has been revamped. Assets are now objects, not datablocks. To drive this point home, t2dImageMapDatablock has been renamed to ImageAsset, which derives from AssetBase (a child of SimObject). You will define an ImageAsset in TAML, not TorqueScript. Example:
Old Code
This looks normal to most of you. To us, it's horrible compared to what we have now.
ImageAsset definition: backgroundImage.asse.taml
Sprite definition in level.scene.taml
Massive reduction in code, far faster, and completely controllable. The point I'm getting at is that you will have transferable knowledge, but none of the written docs will correspond to our changes. Yes, you will need to relearn some class names and fields, but you will learn faster than you did with the old T2D.
09/06/2012 (9:56 am)
@Luis - It's not as bad as you might think. Some concepts will be easier to grasp. For example, the following classes no longer exist:- t2dStaticSprite
- t2dAnimatedSprite
- t2dGrid
- t2dScene
- t2dSceneWindow
- t2dImageMapDatablock
- t2dAnimationDatablock
- and so on
The entire asset system has been revamped. Assets are now objects, not datablocks. To drive this point home, t2dImageMapDatablock has been renamed to ImageAsset, which derives from AssetBase (a child of SimObject). You will define an ImageAsset in TAML, not TorqueScript. Example:
Old Code
// ImageMap datablock definition
new t2dImageMapDatablock(menuBackgroundImageMap) {
imageName = "data/images/menuBackground";
imageMode = "FULL";
useHDImage = "1";
frameCount = "-1";
filterMode = "NONE";
filterPad = "0";
preferPerf = "1";
cellRowOrder = "1";
cellOffsetX = "0";
cellOffsetY = "0";
cellStrideX = "0";
cellStrideY = "0";
cellCountX = "-1";
cellCountY = "-1";
cellWidth = "0";
cellHeight = "0";
preload = "0";
allowUnload = "0";
compressPVR = "0";
optimised = "0";
force16bit = "0";
};
// Static sprite definition
new t2dStaticSprite() {
imageMap = "menuBackgroundImageMap";
frame = "0";
mUseSourceRect = "0";
sourceRect = "0 0 0 0";
canSaveDynamicFields = "1";
PlatformTarget = "UNIVERSAL";
Position = "0.000 -1.000";
size = "1024.000 768.000";
Layer = "5";
CollisionMaxIterations = "3";
AlphaTestValue = "-1";
mountID = "2";
};This looks normal to most of you. To us, it's horrible compared to what we have now.
ImageAsset definition: backgroundImage.asse.taml
<ImageAsset
AssetName="backgroundImage"
AssetCategory="gui"
imageFile="@assetFile=#background.png" />Sprite definition in level.scene.taml
<Sprite
Name="LevelBackground"
image="@asset={GameAssets}:backgroundImage"
SceneLayer="31"
size="32.000 16.000"
Awake="0"
CollisionSuppress="1"
GravityScale="0"
UpdateCallback="1"
SceneId="1">Massive reduction in code, far faster, and completely controllable. The point I'm getting at is that you will have transferable knowledge, but none of the written docs will correspond to our changes. Yes, you will need to relearn some class names and fields, but you will learn faster than you did with the old T2D.
#4
Post-launch work involves a bit more web and community management. Again, we can't have bad documentation being submitted. I'll need to collaborate with David, Chip, and Geoff about post-launch contributions.
09/06/2012 (9:59 am)
@Luis - As for your second question, we could use help pre and post-release. The existing users I trust the most will get early access, if they can help us in some way. One person can help by updating their 3rd party content pack to fit the new system. Another can take the engine for a test drive and report bugs. The person who helps us generate docs will have a special place in my mind and would likely be called upon to help with future changes as well.Post-launch work involves a bit more web and community management. Again, we can't have bad documentation being submitted. I'll need to collaborate with David, Chip, and Geoff about post-launch contributions.
#5
looks like a solid plan
And as for post-launch, you still got time to find a good way to manage the flow of doc submission and filtering away at those - that's good.
One thing you could do in the meanwhile is prepare a list of the biggest changes so that those 'trust the most' users you mention have a little headway in knowing what changes they will face and how those affect the workflow.
Good job all
09/06/2012 (10:09 am)
Understoodlooks like a solid plan
And as for post-launch, you still got time to find a good way to manage the flow of doc submission and filtering away at those - that's good.
One thing you could do in the meanwhile is prepare a list of the biggest changes so that those 'trust the most' users you mention have a little headway in knowing what changes they will face and how those affect the workflow.
Good job all
#6
09/06/2012 (10:14 am)
On the up side, TorqueScript is still TorqueScript (or maybe that's a down side for some). Scripting operates essentially as it always has, but some of the objects have been modernized and altered for speed and simplicity.
#7
09/06/2012 (10:16 am)
@Luis - Certainly. We have been documenting those as we go. While kind of dry, these docs are extremely detailed. They cover topics like the module system, asset system, Box2D integration, and other core integration. These will be critical reading for older T2D users.
#8
True, but as Michael mentions, classes have been renamed, folder structure altered, so basicly you can't call the old console functions in the same way (well, not all).
You have to figure out first wich class they are now under and wether or not their arguments list has changed to accomodate to the new modules system.
Basicly what i mean is that if you have some behaviour out there, chances are it won't work as is
09/06/2012 (10:52 am)
Quote:TorqueScript is still TorqueScript
True, but as Michael mentions, classes have been renamed, folder structure altered, so basicly you can't call the old console functions in the same way (well, not all).
You have to figure out first wich class they are now under and wether or not their arguments list has changed to accomodate to the new modules system.
Basicly what i mean is that if you have some behaviour out there, chances are it won't work as is
#9
09/06/2012 (10:56 am)
I can write docs and tutorials, where do i sign up ;)
#10
@Alienforce - Stay tuned. I'll add your name to the list.
09/06/2012 (11:17 am)
@Luis - I think what Richard was pointing out is that the TorqueScript syntax and general functionality has not changed. So we do have a set of docs that act as a primer for TorqueScript, which can be reused. That's only about 6 total pages, though.@Alienforce - Stay tuned. I'll add your name to the list.
#11
09/06/2012 (11:34 am)
I am always willing to help if you have use for me. I can do testing, reading over docs, and possibly even write basic tutorials. 
#12
09/06/2012 (11:56 am)
Not sure what all is included in writing docs and tutorials, but if you are needing people, I would be very interested in getting my feet wet. 
#13
VERY VERY NICE PLAN.
i do not have t2d/it2d.
if there would have a same plan with t3d,then i could have supply information from my huge note collection of all old useful forum posts
and 3 tutorial that i have left unfinished.
09/06/2012 (12:02 pm)
Quote:Helping us create new documentation will yield rewards. I'd like your opinions on what is worth the effort, but I already have a few suggestions myself
VERY VERY NICE PLAN.
i do not have t2d/it2d.
if there would have a same plan with t3d,then i could have supply information from my huge note collection of all old useful forum posts
and 3 tutorial that i have left unfinished.
#14
EDIT: Fixed my typo of Ahsan's name.
09/06/2012 (12:05 pm)
Oh Ahsan, have we got a deal for you! Just a little longer to wait for our announcement.EDIT: Fixed my typo of Ahsan's name.
#15
When I get something testable I would like to start integration of Python. I could certainly combine that effort with creating documentation of the VM system. I have to modify the VM in order to support Python functions.
In T3D and T2D there is an assumption made that every function that is registered as a callback is registered to 1 console function. Consequently there is no reliable way to determine the correct namepsace of a registered function in the VM. So I had to create another string callback that includes access to the namespace object when the function runs. I use this to check the namespace and function name against my hash table that includes a pointer to the Python function to be called.
That is the kind of thing I could document. Primarily I am not working in the T2D engine, but I want to get more people using my Python stuff to speed up development on this module. The more people that use it, the more it will get improved and fixed. To me this is a win-win situation.
09/06/2012 (12:14 pm)
@Michael,When I get something testable I would like to start integration of Python. I could certainly combine that effort with creating documentation of the VM system. I have to modify the VM in order to support Python functions.
In T3D and T2D there is an assumption made that every function that is registered as a callback is registered to 1 console function. Consequently there is no reliable way to determine the correct namepsace of a registered function in the VM. So I had to create another string callback that includes access to the namespace object when the function runs. I use this to check the namespace and function name against my hash table that includes a pointer to the Python function to be called.
That is the kind of thing I could document. Primarily I am not working in the T2D engine, but I want to get more people using my Python stuff to speed up development on this module. The more people that use it, the more it will get improved and fixed. To me this is a win-win situation.
#17
What I like about it most is that you can create call graphs and it produces a nice set of html docs that have links to just about everything you can think of. Doxygen really helps you get to know new code.
If you learn some of the tags you can include them in the comments of your code to provide more information when the docs are generated.
Another useful addition is to write a script that will parse out function names and variables and create doxygen compatible function and class comment header templates. These can then be filled out by programmers to explain what the variables are for and any other useful information.
Another good practice is to record in this header when the functions are created or changed and which programmer changed them. This allows you to reference a date of the change for repository check out to an earlier version if necessary. Knowing which programmer is changing what can help you find out who you can reference on a particular change.
09/06/2012 (1:29 pm)
Doxygen:) This will create very decent documentation in like 20 minutes literally. Sometimes better than some of the docs for api's I have worked with:) Fact is you don't even have to wait for GG or anyone else you can create the docs yourself!What I like about it most is that you can create call graphs and it produces a nice set of html docs that have links to just about everything you can think of. Doxygen really helps you get to know new code.
If you learn some of the tags you can include them in the comments of your code to provide more information when the docs are generated.
Another useful addition is to write a script that will parse out function names and variables and create doxygen compatible function and class comment header templates. These can then be filled out by programmers to explain what the variables are for and any other useful information.
Another good practice is to record in this header when the functions are created or changed and which programmer changed them. This allows you to reference a date of the change for repository check out to an earlier version if necessary. Knowing which programmer is changing what can help you find out who you can reference on a particular change.
#18
09/06/2012 (1:36 pm)
Watch out Kyle, the word Doxygen can evoke ire in this community since the core TGE docs were compiled from it. I've always liked it myself, but to some people it's a fighting word! 
#19
My site is a social-driven, game development hub. It will feature articles and tutorials on both general game design and Torque based products. It has a huge focus on pushing innovation in game design and and the torque engines to further limits.
Me and other authors will be writing for my site already but I would like to write exclusive content for this site more catered to your needs as well. Definitely contact me with any details, I'm ready to go asap.
09/06/2012 (1:36 pm)
I would love to write docs and tutorials. I make games so making tutorials is more of what I'd like to do for you. I'm actually awaiting this release to start writing tutorials on my own website. So it's a win for both of us. As far as what I'd like, just building up my torque suite would be nice and if that becomes full which I do almost have most of the first party stuff. to be able to give away first party products for promotional contests and such on my personal site would be nice. My site is a social-driven, game development hub. It will feature articles and tutorials on both general game design and Torque based products. It has a huge focus on pushing innovation in game design and and the torque engines to further limits.
Me and other authors will be writing for my site already but I would like to write exclusive content for this site more catered to your needs as well. Definitely contact me with any details, I'm ready to go asap.
#20
In return, all the suggestions are good but have you think to help or sponsorised/bring support on some game projects, for free, games which should come out for promote the new engine. Or simply offer a tool or a pack chosen by the writer for a given quantity of documentation (validated by your team). It would be an exchange of services without the questions of money arrive. By example, for 5 complete documents, you get a tools of your choice, something as this.
09/06/2012 (4:03 pm)
I would love to write a part of the documentation, so it should be more easy to merge my mind with this new version of Torque and to learn it.Quote:What docs do you want to write and what would you like in return?
- Scripting manual
- Class reference
- Reference images
In return, all the suggestions are good but have you think to help or sponsorised/bring support on some game projects, for free, games which should come out for promote the new engine. Or simply offer a tool or a pack chosen by the writer for a given quantity of documentation (validated by your team). It would be an exchange of services without the questions of money arrive. By example, for 5 complete documents, you get a tools of your choice, something as this.
Torque Owner Luis Rodrigues
WinterLeaf Entertainment
I get the idea (maybe I am wrong) that basicly all we know already with the possible exception of some parts of the core engine have already been completly changed (or changed to a degree).
Given this, how can we help with the documentation before actually getting our hands on the product? Or are you just putting this out there for post-release date?
Anyway, great to see things keep flowing