structure of wiki

structure of wiki

Resources to get you going on your new project, or to help you over some emergent problems during your development cycle.

Moderator: Moderators

Post Reply
gajop
Moderator
Posts: 3051
Joined: 05 Aug 2009, 20:42

Re: Wiki: issues + quick questions/answers

Post by gajop »

Split from viewtopic.php?f=1&t=33366 (Silentwings)

I'm going to quote AF from one of the previous threads (viewtopic.php?p=575990#p575983) since it seems wiki related and I doubt it's worth making a whole new thread about it (might split again if I'm wrong).
AF wrote: Right now the top level pages of the Wiki are giant glossaries of sorts. Great if you know what you want and you're drilling your way down, but terrible if you're new. I'd create calls to action at the top of each page for the common new stuff, like "I want to make a new game", no more than 2 or 3 at most. These then link off to an article that in very brief terms describes the super high level structure then provides you with a list of must read items in a recommended order.

That and I'd add a note to the lua docs explaining what Lua_SyncedCtrl or Lua_System are. They're not self explanatory and are frustrating when you're trying to find something and you're not sure which page you'll find it on, the sub headings just aren't enough.

A while ago I built a test site that attempted to index all these things, that was searchable and could be tagged, that would let you view things all at once, or grouped, or see an individual API on its own so that you could comment with code examples and important notes from people who used it PHP style. I can look into setting something up again if that would be useful?
I agree on the premise (that it's hard to get around if you don't know what you're looking for to begin with), but I'm not sure about the proposed way where we'd start with what's basically an introductory tutorial. I don't want to do that (although other people are welcomed) as I'm worried such things tend to get obsolete pretty fast.

I'd be more interested in writing manual/reference pages that hardly exist here. For most cases all we have is a list of functions and we leave it to the user to figure out what they are and how they work. Some places are better than the others (e.g. callins vs callouts) but it's still usually pretty hard to understand the whole system by just reading at the wiki. Something like this would be nice to have I think. (Maybe we are talking about a similar thing?)

Also, if you can show that test site of yours that would be great, but the *ideal permanent solution* should be an extension (or an unlikely replacement) of the wiki.


PS: This is not an invitation to continue the main discussion of that thread which got locked. Keep it addressed to the wiki issue(s) only.
User avatar
AF
AI Developer
Posts: 20687
Joined: 14 Sep 2004, 11:32

Re: Wiki: issues + quick questions/answers

Post by AF »

That would be nice to have, and my proposed starting articles wouldn't be tutorials, they'd be more like a reception that says "I see you want to do X! You'll need to look at A B C D and E, and keep Y and Z in mind". If it said things, it wouldn't be of the form 'this is how you do it' but it would be high level stuff such as
a game is an sdz with these folders, and a file that gives it a name, see here for what each folder does, see here for what goes in the file
I would also say that basic documentation should be auto-generated from the engine. Each function should have its own page, and also appear in a main listing with parameters and a single sentence explanation of what it does.

The other issue is that my test site was built with WordPress. This appears to mortally offend some people who have unreasonable ideas or demands, and such it becomes a political rather than a technical problem. Having said that, the implementation of the test site can be done by anybody without writing any code. To reproduce:

- Install any plugin that registers custom post types and taxonomies
- Install a plugin to enable these to appear in search
- Register a 'function' post type
- Register a tagging taxonomy
- Register a type taxonomy and create 2 terms, synced and unsynced
- Enable comments on the 'function' post type
- Add links to the menu and widgets in the sidebar to list these things
- Fill with content
gajop
Moderator
Posts: 3051
Joined: 05 Aug 2009, 20:42

Re: Wiki: issues + quick questions/answers

Post by gajop »

AF wrote:I would also say that basic documentation should be auto-generated from the engine.
Not sure about auto generation. It sounds ideal but it makes editing the documentation technically require engine changes, which is a rather high barrier of entry (only a select few have push rights and the knowledge+effort to do so is higher than I feel it should be).
AF wrote:Each function should have its own page, and also appear in a main listing with parameters and a single sentence explanation of what it does.
I agree with this and would like to see it happen (also easier linking to functions via buttons or link HTML tags). Is there no way to do it with the existing wiki?
AF wrote: The other issue is that my test site was built with WordPress. This appears to mortally offend some people who have unreasonable ideas or demands, and such it becomes a political rather than a technical problem.
I don't want to get into WordPress or not politics either. The system would have to offer extreme advantages to be considered I think.

AF wrote:That would be nice to have, and my proposed starting articles wouldn't be tutorials, they'd be more like a reception that says "I see you want to do X! You'll need to look at A B C D and E, and keep Y and Z in mind". If it said things, it wouldn't be of the form 'this is how you do it' but it would be high level stuff such as
a game is an sdz with these folders, and a file that gives it a name, see here for what each folder does, see here for what goes in the file
I think we could begin work on this soon - let's call it a manual, but we need some sort of idea how to structure it. If you can provide a structure (or at least a basic skeleton) I'm willing to put effort in it (although more after April's LD) and invite the rest to do the same.
User avatar
FLOZi
MC: Legacy & Spring 1944 Developer
Posts: 6240
Joined: 29 Apr 2005, 01:14

Re: Wiki: issues + quick questions/answers

Post by FLOZi »

gajop wrote:
AF wrote:I would also say that basic documentation should be auto-generated from the engine.
Not sure about auto generation. It sounds ideal but it makes editing the documentation technically require engine changes, which is a rather high barrier of entry (only a select few have push rights and the knowledge+effort to do so is higher than I feel it should be).
Agreed with this criticism.
gajop wrote:
AF wrote:Each function should have its own page, and also appear in a main listing with parameters and a single sentence explanation of what it does.
I agree with this and would like to see it happen (also easier linking to functions via buttons or link HTML tags). Is there no way to do it with the existing wiki?
https://springrts.com/wiki/Lua:Callins# ... erHoldFire

https://springrts.com/wiki/Gamedev:Unit ... holdSteady

Yes, template should be updated to allow a clickable link to make sharing such URLs easier, is on my TODO.
AF wrote:That would be nice to have, and my proposed starting articles wouldn't be tutorials, they'd be more like a reception that says "I see you want to do X! You'll need to look at A B C D and E, and keep Y and Z in mind". If it said things, it wouldn't be of the form 'this is how you do it' but it would be high level stuff such as
a game is an sdz with these folders, and a file that gives it a name, see here for what each folder does, see here for what goes in the file
https://springrts.com/wiki/Gamedev:Structure
User avatar
AF
AI Developer
Posts: 20687
Joined: 14 Sep 2004, 11:32

Re: Wiki: issues + quick questions/answers

Post by AF »

That's a very useful page, but it's not high enough level for what I intended, and it needs breaking into 2 pages as it conflates packages and their internal file structure. Ideally the result would be the sentence in the proposed page would be something similar to:

"Your game will be distributed as a package, containing game files and folders"

Where the bold words link off to the respective pages, or:


- You will need to distribute your game as a package, for information on how to create these, see here
- These packages will contain your game files, for an explanation on the types of game files and their folder structure, see here


Which naturally follows on to a bullet point that leads to a page about PR Downloader, downloaders, Rapid, etc

The goal being that it would be like a starting wiki page, but engineered to be super useful for someone looking at a particular thing, aka wanting to build a game but having no prior knowledge. Once they're familiar with the content they've been directed to from that page, they can refer to the wiki the way other people here do, as a reference. The page itself wouldn't impart very much information at all, merely act as a signpost that joins some high level foundation pages together.
User avatar
AF
AI Developer
Posts: 20687
Joined: 14 Sep 2004, 11:32

Re: Wiki: issues + quick questions/answers

Post by AF »

Re: Auto-generation

I disagree that all documentation should be pulled from the engine. The existence of a callin and its parameters can be autogenerated, but information attached shouldn't be pulled in its entirety from the engine. Pull in any documentation there is, then attach information to the final result, rather than writing article length documentation inside the engine. Otherwise yes we'd be modifying the engine to correct spelling mistakes or changing paragraphs, which is silly, and unnecessary for auto-generation to work.
8611z
Posts: 169
Joined: 08 Jul 2015, 20:20

Re: Wiki: issues + quick questions/answers

Post by 8611z »

Marking changes as "New" or "Outdated" as several uses:
1) It shows readers & editors why this edit was done. (Sets it apart it from trolling and shows some thought when into edit)
2) If you stumble across something in a script/mod that is different to wiki it saves you time to look up which one is correct.
3) Easier to tell if something on wiki is already updated or still needs to be updated. (saves multiple people from doing the same Is-this-updated-already? check)

Wordpress and interblogs or whatever:
-Remember what happend to Q&A answers site, how its content are 'lost', what waste of effort that was.
-Think if it is really nessecary (Why again was forum not good enough for asking & answering questions?)
-Look if mediawiki can not already do thing.

Functions should have their own pages:
1) Think of a name format and create them? wiki/Lua:Spring.GetUnitHealth or whatever.
2) Put any extra information there.
But imo leave current system, most function names are self-explaining. Use the extra pages for examples or whatever.


"It is not obvious what page to look at find some function that does XYZ":
As I see the answer to such questions means figuring out if the wanted function is..
a) read b) get c) synced d) unsynced e) a callin
a+b) The difference between Get/Set functions is common concept.
c+d) Synced/Unsynced is less obvious and there are some tricky cases. But after a while or short tutorial I think the idea is also quite clear. ("CreateUnit() must be a synced function or else every player could cheat him self nuke silos", "widgets are limited to reading what the player sees to prevent map hack cheats.")
e) A function that gets callend when an event happens.

This 'drilling down' is how documentation and manuals work.
You start at index/glossary and keep click stuff until you arrive at relevant pages.

Not sure what excactly some posts mean but a manual in self-explaining way is better than a manual that needs explaining:
Definition Files
Gamedev:UnitDefs
Gamedev:WeaponDefs
The page titles tell you want to find there.
Definition Files
- Gamedev:UnitDefs - define the attributes of units
- Gamedev:WeaponDefs - define the attributes of weapons/projectiles
Okay, but the description just repeat what the page names say without adding new info.
Q: I want to alter the attributes of units. Where to look at?
A: Look at Gamedev:UnitDefs there you find a page about the definition files of units, meaning files that defines the attributes of units.
Thank you Captain Obvious?
User avatar
FLOZi
MC: Legacy & Spring 1944 Developer
Posts: 6240
Joined: 29 Apr 2005, 01:14

Re: Wiki: issues + quick questions/answers

Post by FLOZi »

I agree with knorke, but https://springrts.com/wiki/Mapdev:Main is still better than the gamedev version, and all the gamedev tutorials should be nuked and replaced, but it is conceptually difficult and increasingly so the more open Spring becomes. Setting out to make fLove is totally different to setting out to make BAR, surely?
User avatar
Silentwings
Posts: 3720
Joined: 25 Oct 2008, 00:23

Re: Wiki: issues + quick questions/answers

Post by Silentwings »

Actually I disagree, I much prefer the layouts of https://springrts.com/wiki/Gamedev:Main and https://springrts.com/wiki/Lua_Scripting to https://springrts.com/wiki/Mapdev:Main.

I would like to see some friendlier game/lua tutorials (although at this point I'm not a customer for them), but I would rather the focus of the wiki kept its current "dictionary" style, with verbose tutorials & intros as separate pages.

I don't view the abstraction of Spring away from hardcoded game mechanics as a barrier to writing tutorials - but it does mean that beginners tutorials should focus on methods (e.g how to add a unit to C.sdd) rather than "how to create a functioning game in a single page".
gajop
Moderator
Posts: 3051
Joined: 05 Aug 2009, 20:42

Re: Wiki: issues + quick questions/answers

Post by gajop »

One issue I find in the wiki is that there's no page telling you how to add a single unit(def) to the game.
You pretty much should read most of the GameDev section to familiarize yourself enough to do it, as you definitely need to know:
- unitdefs
- scripts
- movedefs
- covols
- how to add models & textures (this last bit is what the minimum SHOULD be!)

This is what you need to read if you just want to add a unit that does nothing except appear on the map and has collisions corresponding to its visual properties.

1) With that in mind, I wish the engine didn't require us to write script files that do nothing.
This should be the default script file when nothing is provided: https://github.com/SpringCabal/Flove/bl ... rigger.lua

2) Better default collision volumes that just work out of the box (usePieceCollisionVolumes = true by default). You can optimize it for speed later. The same applies for yardmaps and other unitdef values (less mandatory writing).

The problem is both require engine changes (or at least this) which isn't the discussion here..
So what I'd propose we do is write a page detailing all the information required to get a _finished_ model and texture ingame. Not necessarily step by step but instead something detailing the required parts and giving link to the appropriate GameDev subsections.

PS: Agree with Silentwings, especially the last sentence.
8611z
Posts: 169
Joined: 08 Jul 2015, 20:20

Re: Wiki: issues + quick questions/answers

Post by 8611z »

One issue I find in the wiki is that there's no page telling you how to add a single unit(def) to the game.
You pretty much should read most of the GameDev section to familiarize yourself enough to do it, as you definitely need to know:
- unitdefs
- scripts
- movedefs
- covols
- how to add models & textures (this last bit is what the minimum SHOULD be!)
-unitdefs = https://springrts.com/wiki/Gamedev:UnitDefs
-scripts = https://springrts.com/wiki/Gamedev:Main ... n_of_units
-movedefs = https://springrts.com/wiki/Movedefs.lua
-covols = https://springrts.com/wiki/Gamedev:Unit ... on_Volumes , https://springrts.com/wiki/Gamedev:CollisionVolumes
-models & textures = https://springrts.com/wiki/Gamedev:Main ... 6_Textures

That info is all there and reachable from the https://springrts.com/wiki/Gamedev:Main too.
And yes, to find out how it is done you have to read those pages.

What is missing? A page like this?
superpro tutorial wrote:Look at the unitdef page to look how to make unitdefs.
Look at the unit script pages to look how to script a unit.
...
There are so many different ways to make mods, from scratch or editing other mods.
Depending on what one wants to do there might be no need to look at models or scripts or movedefs.
It is up to the user to figure out what he wants to to and what info/skills/tools he needs.
What are the differences? The layouts all look the same to me.


https://springrts.com/wiki/Mapdev:Main#Common_Problems "Common Problems" should not be a subsection but its own page.

The Beginner-Tutorial should be its own page and not that subsection with description plus three links.
And again, a manual that needs explaings:
"This beginners tutorial is split into three parts, the basic stuff, the more advanced basic stuff, and how to compile and create a map archive for distribution"
Such sentences are only nessecary because the three parts have non-self-explaining names:
-Stage 1
-Stage 2,
-Finalizing

With better titles no more explaining is nessecary:
-Basic map with heightmap & texture
-Optional textures, adding objects, lighting
-Compiling & packing

Otherwise this map-tutorial is actually quite good. Unlike other map-tutorials or the complete-mod-tutorial it is NOT re-creating redundant info.
For example in the part about heightmap:
https://springrts.com/wiki/Mapdev:Tutor ... Height_map
It does not repeat all the stuff about black pixels =low, white pixels =high, or what resolutions, instead it recommends to check out the relevant pages.

all the gamedev tutorials should be nuked and replaced
All? It is not like many exist.
Right now I only know of one gamedev tutorial is still not clearly marked/unlinked:
https://springrts.com/wiki/The_Complete ... pring_Game
As far I can see everything else is already marked as Deprieacsoited, striked through or not linked to anymore.
Oh and the complete "Game Development Tutorials & Resources" subforum.
but it is conceptually difficult and increasingly so the more open Spring becomes
Whatever that is supposed to mean.
The problem with removing old/redundant stuff is that there is always hoarders who block it or claim it will get updated.
But that never happens because because there are already better, properly structured pages and there is no need for the other mess.
See subforum "Game Development Tutorials & Resources" or the complete-mod-tutorial that nobody updates either.
Or this:
https://springrts.com/wiki/Gamedev:Main wrote:Simple Game Tutorial - needs to be updated
How much time needs to pass until people realize that nobody will update it, ever, and such stuff gets cleaned up?
gajop
Moderator
Posts: 3051
Joined: 05 Aug 2009, 20:42

Re: Wiki: issues + quick questions/answers

Post by gajop »

8611z wrote:What is missing?
The point is that you don't know what you should be reading. There is nothing that tells you what you should be specifying when adding game assets. How is the user to know about that list? To me it seems reasonable to think about scripting and movedefs only if you plan on actually doing it, and you certainly shouldn't need to read the entirety of unitdefs just to get stuff in game.
8611z wrote:A page like this?
superpro tutorial wrote:Look at the unitdef page to look how to make unitdefs.
Look at the unit script pages to look how to script a unit.
...
No, but something like this would be good to have:

1) A beginning introducing the developer to units and features, their differences and use. Something akin to http://docs.unity3d.com/Manual/GameObjects.html and some of the subsections there.
2) An overview of how units are defined, the fact that you must define a type (def) and associate it with a model and scripting file.
3) How unit movement/actions are controlled and what scripting and movedef files are (this is something that should be in the next step of the manual as scripting should be optional)
and so on

We know that these are the fundamental building blocks of a unit, but new users might not. This needs to be explained somehow and it could be done as a manual.
Super Mario
Posts: 823
Joined: 21 Oct 2008, 02:54

Re: Wiki: issues + quick questions/answers

Post by Super Mario »

Windows development page needs updating. Some of the warnings is not needed. The compile time difference is around 2 minutes when comparing linux with windows.
8611z
Posts: 169
Joined: 08 Jul 2015, 20:20

Re: Wiki: issues + quick questions/answers

Post by 8611z »

"Get stuff ingame" or "adding game assets" is broad and vague.
It can mean anything from replacing one audio file to a completly new unit or map.
So you look at https://springrts.com/wiki/Gamedev:Main or https://springrts.com/wiki/Gamedev:Structure and then decide from the headings/descriptions what you want or need to read.

Wants to give the Peewee a stronger laser? Then look at def files and scripting is not nessecary.
Wants to give the Peewee a nicer animation? Then scripting is mandatory.

The first challenge is usually unpacking a mod so that you can edit it, as well as figuring out a few basic how-to-develop things.
The info for that is here:https://springrts.com/wiki/Gamedev:Archives , https://springrts.com/wiki/TestingYourGame
If that is too hard to find then it might be something where tutorial could make sense.

Beside that there are no "next steps" and you can not tell what is "optional" or not.


Some stuff is also kinda selfexplaining or obvious, what would you expect if a unit has no model or script? You would either expect crash or failure to load or that nothing happens. I doubt that users are surprised when their unit has not defined a script and as result does not function/animate.

To most modding problems exist different approaches and they all use different things.
Say you want to highlight positions on the map to mark resources or spawnpoints or whatever.
You have several options:
- Should it be done by the game or by the map?
- - Paint the stuff onto the map texture?
- - - Use diffuse or make it shiny maybe?
- Or instead maybe use features OR units?
- - What model & texture format? 3do, s3o, assimp?
- - Should the script be LUS or cob?
- Or maybe use Lua to draw something?
- - With spring-markers or gl?
- - gl has tons of different ways obviously
- Or maybe use particle effects to mark the locations?
- - CEG or Lups?
- ...
That is all answers to the problem and it is all very different.
What is the best option depends on many factors, and no tutorial can answer that.
It depends on how much time do you want to invest, what skills and files do you already have, what works best with the mod you are using/making.

So in short, for most topics I do not see the use more of introduction or overview-texts or whatever when it is clear enough from the content/structure itself. However those texts bring the risk of quickly being forgotten and outdated.
In the areas where one might see need for "better overview" the problem is more the lack of that content or structure.

---
random stuff that is somewhat important and sucks:
Everything around models & textures.
https://springrts.com/wiki/About_s3o has empty sections about textures with "needs info" when textures have their own page here: https://springrts.com/wiki/3DModels:Textures
https://springrts.com/wiki/Basic_s3o_unit_making_guide - all around quite bad, vague, OTA stuff, overlaps with other pages,..

Also sometimes authors do not know something 100% sure, there needs be better way to mark that.
For example instead of writing:
"If I'm not mistaken ... "
"It's reported that ..."

it is better to write as if it was fact and use FIXME template with question mark or so.
User avatar
FLOZi
MC: Legacy & Spring 1944 Developer
Posts: 6240
Joined: 29 Apr 2005, 01:14

Re: Wiki: issues + quick questions/answers

Post by FLOZi »

8611z wrote:
all the gamedev tutorials should be nuked and replaced
All? It is not like many exist.
Right now I only know of one gamedev tutorial is still not clearly marked/unlinked:
https://springrts.com/wiki/The_Complete ... pring_Game
As far I can see everything else is already marked as Deprieacsoited, striked through or not linked to anymore.
Oh and the complete "Game Development Tutorials & Resources" subforum.
Guess I already nuked all the others then, though I really meant deletion rather than merely deprecation.
but it is conceptually difficult and increasingly so the more open Spring becomes
Whatever that is supposed to mean.
It means precisely the same as:
That is all answers to the problem and it is all very different.
What is the best option depends on many factors, and no tutorial can answer that.
It depends on how much time do you want to invest, what skills and files do you already have, what works best with the mod you are using/making.
The problem with removing old/redundant stuff is that there is always hoarders who block it or claim it will get updated.
But that never happens because because there are already better, properly structured pages and there is no need for the other mess.
See subforum "Game Development Tutorials & Resources" or the complete-mod-tutorial that nobody updates either.
Or this:
https://springrts.com/wiki/Gamedev:Main wrote:Simple Game Tutorial - needs to be updated
How much time needs to pass until people realize that nobody will update it, ever, and such stuff gets cleaned up?
I don't disagree, but short, to-the-point tutorials on creating e.g. a single unit and all the relevant files to do so or how to script e.g. a factory will be useful and are on my long long TODO.
8611z
Posts: 169
Joined: 08 Jul 2015, 20:20

Re: structure of wiki

Post by 8611z »

Why was this thread moved/split to "Game Development Tutorials & Resources"?
The subforum that should be removed/closed because everything inside is outdated old / wrong / duplicate? Rename it "old stuff / trashcan" and unsticky it from Content Development already, instead of moving more stuff there. This thread is not even a tutorial or similiar.

There is no reason why bad pages must be gone completly. Seems like overreaction.
There are enough ways to move stuff to virtual trashbin where it can still serve as example of what to avoid. Imo some stuff has historical value too. (King-of-Mod-XY pages, emmanuelistic pages etc)
Marking the page and removing all links to it is enough & better.
Post Reply

Return to “Game Development Tutorials & Resources”