Spark SDK Manual - Updated 19/July/2015
Summary:
Access the current weekly build of the manual here.
Contribute Directly via GitHub Here.
Provide feedback by posting in this very thread...
Original Post:
Current Progress:
Access the current weekly build of the manual here.
Contribute Directly via GitHub Here.
Provide feedback by posting in this very thread...
Original Post:
Hello, recently(about 2 days ago) I decided to write an unofficial manual for the spark engine sdk (software development kit). Before I get too far into it, I'm just curious as to what other people think of the current state of documentation?
Is this needed? Is it wanted? Is it already done somewhere?
I intend to cover four major categories: Concepts, Tools, Reference and Instructions.
Concepts are the way the spark engine works and handles things, why it handles them. Information on what underlying technologies are there, how they work and how you should think about it (e.g. ns2's implementation of lua).
Tools are the tools explicitly provided in the NS2 install for modding the game, so that'll be: launchpad, spark editor, decoda and a bunch of other things like builder.
Reference will be specifications (prop limits, performance figures, model specs etc), entire available script description, that sort of thing.
Finally Instructions are essentially tutorials, but I feel the term instruction fits better. That will go over individual self contained tips on how to do things and how best to do certain things.
I will be reaching out for help once I've solidified the documentation style and I've almost formulated a nice way on how people can help out.
I may custom code a html/javascript website, I may use media wiki or I may use wikidot to host it. Not entirely sure. For now it'll be stored as open document text files.
So yeah, what do you think about writing an unofficial manual on the spark sdk? and who would be interested in writing content for it?
Is this needed? Is it wanted? Is it already done somewhere?
I intend to cover four major categories: Concepts, Tools, Reference and Instructions.
Concepts are the way the spark engine works and handles things, why it handles them. Information on what underlying technologies are there, how they work and how you should think about it (e.g. ns2's implementation of lua).
Tools are the tools explicitly provided in the NS2 install for modding the game, so that'll be: launchpad, spark editor, decoda and a bunch of other things like builder.
Reference will be specifications (prop limits, performance figures, model specs etc), entire available script description, that sort of thing.
Finally Instructions are essentially tutorials, but I feel the term instruction fits better. That will go over individual self contained tips on how to do things and how best to do certain things.
I will be reaching out for help once I've solidified the documentation style and I've almost formulated a nice way on how people can help out.
I may custom code a html/javascript website, I may use media wiki or I may use wikidot to host it. Not entirely sure. For now it'll be stored as open document text files.
So yeah, what do you think about writing an unofficial manual on the spark sdk? and who would be interested in writing content for it?
Current Progress:
(7/10/2013) Finished Interface overview: Other windows, Console Output and Infobar.
(6/10/2013) Finished writing explanation of the viewport(s).
(5/10/2013)Finished writing descriptions for the file menu area, also wrote a description for the toolbar area.
Started Documenting The Spark Editor(4/10/2013). Currently working through the most boring bit (the top file menu area).
No further progress will be posted in this spoiler, see the github for news or just read through the thread.
(6/10/2013) Finished writing explanation of the viewport(s).
(5/10/2013)Finished writing descriptions for the file menu area, also wrote a description for the toolbar area.
Started Documenting The Spark Editor(4/10/2013). Currently working through the most boring bit (the top file menu area).
No further progress will be posted in this spoiler, see the github for news or just read through the thread.
Comments
Why should it be done? Simple: To lower the barrier for people to modify Spark and encourage larger mods to be developed.
This needs to be kept as official as possible, having the resources scattered all over the place and not in "official" locations won't help.
I'll volunteer some of my time to this. Having a cohesive and comprehensive, single location, to go for all the development questions for Spark is something that is seriously lacking. I think more people would be working on their own projects if this "problem" was solved.
There is a sort of commitment that will come with starting something like this however. It will need to be updated and reviewed every time an update comes out.
Long story short, I recommend using the official Wiki as much as possible. Also, this is NOT a project to be taken lightly. All told, this will be a LOT of work.
http://wiki.unknownworlds.com/ns2/Modding
As for the official ns2 wiki? I'd rather use a different solution because the colour scheme just doesn't seem conducive to learning. Also I'd have more control over something else.
Thanks for the motivating comments guys, you'll be seeing lots of questions in the forums in the near future asking about stuff I'm not sure about.
From my experience, it's much more valuable to understand UWE's "functional / design goals" for a given chunk of code. Having inate knowledge of what XYZ functions are and their declarations won't get you very far. It's vastly more important to understand WHAT is being done, instead of HOW it's being done. This seems like I'm stating the obvious; however, in my experience (and from helping out others, in addition to my professional experience) far too many people expect documentation that is going to hold their hand, and guide them on a wonderful journey of learning. At the end of said journey, they'll have the know-how to make something. In reality, it's far more beneficial to jump in head first and start DOING. Yes, it will be frustrating, but in the end you'll have a much greater understanding and be able to make more of your ideas come to fruition.
Anyways...I wasn't trying to give a finger wag or go into anything resembling rant-mode. I have the nagging suspicion that lots of people have a very similar sentiment like the one @DarkOmen expressed. Modding for NS2 is kind of hacking. Spark / NS2 doesn't have a clean-cut, laser sharp API that can be molded into anything. I cannot stress this enough, Spark is not Unity and never will be.
Please, do not misunderstand me! I WANT hundreds, no, thousands more people crafting mind-blowing things for Spark & NS2. Truly.
Hell, I'd love to see brand new non-NS2 games. Yes, that IS possible.
In practice though, the only way that will really happen is if people dive in, and "just start modding".
@McGlaspie I feel the same way about documentation.
There are three major goals of this documentation project. The first is to explain the concepts behind the spark engine. That one is difficult to explain but it's a safe bet that the stuff in the spark engine is coded to some sort of a pattern and I intend to convey that to the people reading the manual.
The second goal is to describe all of the tools and what they do. People will be able to take that information and figure out how to do stuff with the tools if they know what everything is without fumbling around.
The third and final goal is the closest you'll see to a tutorial in the manual: Best practices. Best practices isn't really best practices, but it's a good approximation, and will detail things like workflows, optimisation and specific little things on good/great ways of achieving certain things.
An easy example is: Best practices for creating a level.
As for current progress, I've decided to use wikidot as it's a simple and mostly free solution. I'll detail how people can contribute in the near future, but the basics of contribution: You must write an article and have it ready to go before I'll add you as an official contributor. That's to stop people from signing up and never doing anything.
Addition:
Oh and, the manual is targeted mostly at people with little experience in programming, level creation and modding in general. As those are the people who really need it. Anyone with modding experience from say, source engine or lua programming experience can figure out what's going on. But a complete beginner needs a platform to cling to. This manual intends to be that platform.
- I'm using git, specifically GitHub to manage the project.
- I'm using reStructuredText with Sphinx to build the documentation.
- I'm creating a full Development handbook which will not only cover the tools but also the concepts necessary to make anything happen in the game.
Because it's on GitHub as a public project, that means anyone can clone it, modify it and submit a pull request with their changes to be reviewed and brought in, a bit like a wiki only with a slight delay and a tiny bit of quality checking in there.
I'm a little bit excited about this even though it's super late in the game. I hope that we can make this documentation successful and pull some of that development knowledge out of the more experienced modder/developer's heads (Looking at you @McGlaspie ).
I'll update the main post eventually (when there's something really worth showing), but for the meantime here's a link to the current state of the Handbook, it's only a basic skeleton and is most definitely a work in progress with major structural changes open for discussion.
(Unofficial) Natural Selection 2 Development Handbook HTML version
I can also build pdf and epub and whatnot versions too because I'm using Sphinx.
====================================
Okay that's awesome, but what if you want to help out? There are a few options:
Directly Help Out:
You can head over to the official GitHub page and do the whole git/github dance to clone the repository, make some changes and submit a pull request. If you need a little help setting this up, I'm definitely here to help out, just reply right in this thread or send me a pm.
P.S. I'm still learning git/github myself so don't expect expert advice from me though.
Indirectly Help Out:
Join in the discussion right here in this thread. I am betting that there's still enough people with experience modding ns2 on these forums that they will see this and will gladly throw their opinions about the handbook my way. If you are such a person, please join in! Point out problems in the handbook like incorrect or missing information, spelling mistakes, ways things could be reworded.
Point out suggestions for how the manual could be structured better (don't like how there's a bunch of topics and then all the manuals lumped together? say so!).
====================================
Once again, I'm looking forward to see how this goes, I'll be the rock on the project pushing(or pulling) it forward a little bit every day, but it'll be up to the rest of you to throw information my way as I'm not experienced enough with NS2 development to make this happen quickly myself.
Thanks for reading!
you get the updates literally as fast as I type them down.
Anyone will be able to comment on the guide (I will put my trust in you to not abuse this feature).
In order to give direction to the project, I am going to be making mods. One at a time.
I'll have the google docs up in a while (no ETA, no more than a week) depending on my workload with other stuff.
Thanks for reading!