TOC rework

[Zehir]

The goal is to cleanup the TOC and sort / edit somes pages.

#23

[Zehir]

Poll : Split Spawnable Objects into Built-in and Custom

[Zehir]

Poll : Moving Player-color into Types

[Benjamin-Dobell]

Poll : Moving Player-color into Types

Will player color get its own tag? How many methods simultaneously accept player colors and team names?

[Benjamin-Dobell]

I'm a bit worried about making player color a formal type. In general, I think it's a good idea. However, it's edge cases that worry me. Like places where team names are accepted as well as colors, or places where "Black" and/or "Grey" are forbidden etc.

[omniraptorr]

i don't know if team names are used anywhere in the api except in functions that explicitly deal with teams.

[Benjamin-Dobell]

I know Visibility Targets accept combinations of colors, team names etc. However, it's XML and might be a singular exception.

[Zehir]

Poll : Have a Player Color type

[Zehir]

We have received complaints about the new table of contents so I am reopening this issue

[Zehir]

What about keep 3 level (Scripting API / Game Component / Grid) but when we open Scripting API it open all the way down ?

[Eldinnie]

I don't understand what you mean here

[Zehir]

When I click on Scripting API, he open all the sub list too

[Eldinnie]

What do you mean with What about keep 3 level (Scripting API / Game Component / Grid)?

[Zehir]

Scripting API is level 1
inside we have Game Component level 2
and inside we have Grid level 3

[Eldinnie]

So If I understand you correectly. What you;re saying is, keep the grouping, but unfold it all always? Then what is the point of grouping?

[Zehir]

To keep them organized into categories

[Eldinnie]

I think it would jsut become confusing.
From a list showing:

Scripting API
|- Object
| ...
|- Wait
| ...
|- Grid

You'd go to

Scripting API
|- Game Object
   |- Object 
   | ...
|- Game Component
   |- Grid
   | ...
|- Scripting Component
   |- Wait
   | ...

I'm sorry, but I really fail to see why that would be better...

[Benjamin-Dobell]

Hmm, I don't mind the 3 levels, however I don't think the way things are currently categorised is all that intuitive.

I'd steer clear of the term "Component" unless referring to the Component API.

Also, I don't think the 3 chosen categories are the best way to break things up. Take for example, "Lighting", it is under "Game Component", whilst "Physics" is under "Scripting Component". To me, they'd both be better categorised as under something like "Scene Configuration".

[Zehir]

Ok i drop it, do as you want

[Eldinnie]

Althought the most important and used function in Physics is cast, which has nothing to do with Scene configuration

[Benjamin-Dobell]

@Eldinnie Yeah, I was just writing a follow-up to that...

Even Configuration doesn't sound right actually, because there's both setGravity() (i.e. configuration) and cast() i.e. querying the scene. Perhaps something like "Scene APIs". Anyway, I like the idea of breaking things up further. Just think we're going to need to have a discussion about what goes where.

[Zehir]

Ok so we mix everything in the same bag while waiting for better

[Benjamin-Dobell]

Umm, if it can be cleanly reverted, sure. It doesn't seem urgent to me though, think it could just be improved upon, so if it won't cleanly revert, don't waste any time on it.

[Zehir]

I will just make a commit on master do groupe everything back if it's ok for you

[Benjamin-Dobell]

Sure, go for it.

[Benjamin-Dobell]

So just spit-balling here. This isn't so much a TOC overhaul, as an entire structure overhaul, however what about something like...

• Introduction
• Objects / Types
  • Basic Types (i.e. The existing Types page.)
  • Object
    • Object Types
    • Common Properties
    • AssetBundle
    • Book
    • Browser
    • Clock
    • Counter
    • RPGFigurine
    • TextTool
    • Components (Advanced)
  • Player Color
  • Player
    • Properties/Methods
  • Utility Types
    • Color
    • Vector
• Global Script
  • Context (Quick explanation and link to Global Reference.)
  • Events
• Object Script
  • Context (Mention self and link to Global Reference.)
  • Events
• Scene
  • Grid
  • Lighting
  • Physics
• Spawning Objects
  • APIs
  • Built-in Objects
  • Custom Objects
• Turns
• User Interface
  • Music Player
  • Notes
  • UI
• Utilities
  • General
  • Chat / Logging
  • JSON
  • Time
  • Wait
  • Web Request
• Global Reference

Why?

Discoverability is a major issue with the current docs.

To be clear, I'm not talking about having everything directly accessible at once. A flat hierarchy does that. I'm more thinking about how a brand new user is going to try find information i.e. grouping by functionality,

Base

The current Base really doesn't convey anything meaningful. If you want to know what global functions exist, you'll be looking for the word "Global". If you want a message to appear in the chat pane, then you're going to be looking for "Chat" (or something similar).

I propose we add the method descriptions to other pages where the logically make sense. Like copy(), paste(), group(), getObjectFromGUID(), destroyObject(), spawnObject() and spawnObjectJSON() being grouped with the Object APIs.

startLuaCoroutine() should be under a "Utilities" -> "General" as above, and the messaging methods under "Chat / Logging"

It's reasonable to keep a reference of all the Global functions (Global Reference), in case someone wants to peruse what's available. However, when you're logically trying to work out how to broadcast a message to a player "Base" certainly doesn't spring to mind!

Events

Split up into Global and Object, as above. I would suggest in the Object -> Events page having a section called "Global Events" where it specifically explains that several events pertaining to objects are broadcast as Global events, such that they can be handled in the Global script.

Object & Global Script

I know it's in the intro, but I don't think users get this. I think it needs to be more explicitly called out in the API structure. Given that all object events are now accessible as global events as well, we can even make the suggestion that if you're building "Redistributable Component", use an Object Script, if you're building a mod, use the Global Script.

In the Object -> Context we should make it clear there is a self variable and to refer to Types -> Object, can even include a link to the Types -> Object -> Common Properties`.

Turns

This is a tough one, I somewhat wanted to put it under User Interface, because it does pertain to that, however seems as it affects gameplay directly, that just didn't seem right.

[Benjamin-Dobell]

Doing the above, we could probably ditch the "Scripting API" category altogether, pull everything up one, and then move "UI API" to "XML UI" under "User Interface".

Would just need to rejig the "Scripting API" -> "Introduction" a little bit seems as there's already a "Getting Started" category.

[Zehir]

This seems good but I would like to put Player Color under Player.
What you put under Spawning Objects / APIs ? spawningObject and spawningObjectJSON ?
And what about putting Turns in User Interface ?
What is in Global Reference ? And put in below Global Script ?

Edit : And probably group Utility Types and Utilities
Edit 2 : And what about linking the api page with the knowledge base page ?

[Benjamin-Dobell]

This seems good but I would like to put Player Color under Player.

The reason I didn't do this is because Player Color is its own top-level "type" (really a string). It's something that you regularly interact with on its own (parameters etc.) If you look at Object, it has types under it, but those types are only found on Object, there's no other way to ever get a reference to those types without going through an Object.

What you put under Spawning Objects / APIs ? spawningObject and spawningObjectJSON ?

Yes.

And what about putting Turns in User Interface ?
What is in Global Reference ? And put in below Global Script ?

Please see my initial comment below the TOC layout, both of these are explained.

However, just to clarify on Global Reference in particular, it's not related to Global Script, it's the list of functions (but not their descriptions) from the current Base page. In general Global Reference is not very useful when searching for functionality because it explains nothing about its contents, like the existing Base page. Instead it's just there for posterity, in case someone simply wants to see everything that is available as a global function, instead of looking for a specific piece of functionality.

Edit : And probably group Utility Types and Utilities

There's already a Utilities group down the bottom. The difference is a Type is something you can have an instance of i.e. there's multiple of every type described under Objects / Types. Where as the Utilities down the bottom are just a collection of functions.

Because Utility Types comes under the category Objects / Types I also think it's worth making the distinction that these are types and not objects.

Edit 2 : And what about linking the api page with the knowledge base page ?

Do you mean hosting our own copy?

The knowledge base has some useful info, however it's both very out of date and unusual in that it contains content for both regular gamers and modders in the one place. Rather than invest any time in it, I'd rather work on https://tts-community.github.io instead.

Unlike Berserk, we have more freedom to include guides for third-party libraries and tooling. Rather than everyone reinventing the wheel all the time, I'd like to give this (hypothetical) content as much visibility as possible. So if anything I'd like to add a bunch of links to the TTS Community main site. However, the TTS Community main site should itself link out to the knowledge base.

Basically I just don't want users thinking the knowledge base is all there is.

[Zehir]

OK I see, this seems fair for me. Let see what other think about this.
About the knowledge base, there is already some links to it in api. But how users will understand how the api work if they don't understand how the game work with an outdated kb ?

[omniraptorr]

i responded to benjamin's suggestions inline. https://dynalist.io/d/ywVFIPTkH-zevM2Ka1RIdsTk#z=LIL0lQeZvP83hld_2mbPy7x6

[Eldinnie]

Looks good in base, but I would still really appreciate it if this wouldn't fold by default, only when users fold it.

Some specific things:

I would love to see Player Color in the Color utility. They're in there anyway (or at least should be). And it being a top level entry now is rather weird imo. It really fits within the Color class.
Alternatively it should be a subcat of types. Or both (see below)

When this would go through I would expect Object Script to be a subcat of Objects/types. I understand having it at the same level as Global Script has a benefit for clearity though

If you're splitting the events. You should at least cross-reference the ones that are global and object specific. So onHover() should mention the existence of onObjectHover and vice versa. Having them close to each other is definitely a pro if you want to decide which is more useful for you case.

The utility types should be a subsection of the basic types. (it extends the basic types with types with functionality. Either way it's a type and should fall under that heading.

I suggest combining Scene, Turns and User Interface into Gameplay utilities That seems a god overarching term for these. Definitely link to Physics.cast in some places, like getObjects(), Utilities -> General and other proper places.

[Eldinnie]

Actually, come to think of it. I think Objects/types is not a good category.
Start with

• Types
  • Basic Types
  • Player Color
  • Vector
  • Color
  • Object Types (Assuming this is the spawnable objects page?)
• Object
  • etc.

[Benjamin-Dobell]

@Eldinnie The reason I like Objects / Types is that everything that goes in there you can have an "instance of". Everything else is effectively just namespaced methods.

[Eldinnie]

@Benjamin-Dobell Yes. Just preference maybe. Object is so big it should be seperate imo.