Document SDLs in more detail

[Attagoat]

Throughout my time playing H'uru I've noticed that there a lot of SDL files and many of the variables are not well documented for what changes what in an age. Will be adding a checklist for myself later on what needs to be documented. I would be willing to take on this project.

• [x] ahnonay.sdl
• [x] ahnonaycathedral.sdl
• [ ] animations.sdl
• [ ] avatar.sdl
• [ ] ayoheek.sdl
• [x] BaronCityOffice.sdl
• [x] ChisoPreniv.sdl (Documented Already Thank you Doobes!)
• [x] city.sdl
• [x] Cleft.sdl
• [ ] cloneMessage.sdl
• [ ] clothing.sdl
• [ ] Dereno.sdl
• [ ] Descent.sdl(Will probably be updated as work on Descent continues)
• [ ] EderDelin.sdl
• [ ] EderTsogal.sdl
• [ ] Ercana.sdl
• [ ] ErcanaCitySilo.sdl
• [ ] Garden.sdl (Eder kemo)
• [ ] Garrison.sdl
• [ ] Gira.sdl
• [x] GoMePubNew.sdl(Documented Already, Thank you Doobes!)
• [ ] GreatTreepub.sdl
• [ ] GreatZero.sdl
• [ ] grsnTrnCtrDoors.sdl (No idea what this is)
• [ ] Jalak.sdl
• [ ] Kadish.sdl
• [ ] Kveer.sdl
• [ ] Minkata.sdl
• [ ] morph.sdl
• [ ] Myst.sdl
• [ ] Negilahn.sdl
• [ ] Neighborhood.sdl
• [ ] Neighborhood02.sdl
• [ ] Nexus.sdl
• [ ] particle.sdl
• [ ] Payiferen.sdl
• [ ] PelletBahroCave.sdl
• [ ] Personal.sdl(Relto)
• [ ] PhilRelto.sdl
• [ ] physical.sdl
• [ ] responder.sdl
• [ ] RestorationGuild.sdl(Not sure what this is)
• [ ] Serene.sdl
• [ ] sound.sdl
• [ ] spyroom.sdl
• [ ] Teledahn.sdl
• [ ] Tetsonot.sdl
• [ ] Tiam.sdl
• [ ] tldnPwrTwrPeriscope.sdl(Not sure what this is)
• [ ] tldnVaporScope.sdl(Not sure what this is)
• [ ] tldnWRCCBrain.sdl (not sure what this is)
• [ ] trebivdil.sdl
• [ ] VeeTsah.sdl
• [ ] Vothol.sdl
• [ ] x2wayLever.sdl
• [ ] xAgeSDLBoolActivatorComboSet.sdl
• [ ] xButtonLeverSwitchPowered.sdl
• [ ] xChatChannel.sdl
• [ ] xConcentration.sdl
• [ ] xHighLevelStarTrekDoor.sdl
• [ ] xPassiveIndicatorLight.sdl
• [ ] x.PoweredLightSwitch.sdl
• [ ] x.PoweredStarTrekDoor.sdl
• [ ] xregion.sdl
• [ ] xStateToggler.sdl
• [ ] xTelescope.sdl

[Deledrius]

I suspect that most documentation on which Age SDL variables change which features was internal-only at Cyan, if they had documentation on it at all. The rest is as-is in the files themselves, or by looking into the Age itself. Generally the names tend to be at least somewhat self-documenting, but there are more than a few obscure ones.

For the sake of maintainability, I think adding new comments to the files (rather than documenting them elsewhere which can become out of sync) would be the best strategy. Hopefully other maintainers can chime in on that with their thoughts as well. I look forward to your contributions.

[Attagoat]

@Deledrius I agree with you which is why I am working on adding comments to the SDLs

[Attagoat]

Alright, I added the checklist.

[Hazado]

RestorationGuild.sdl - This is the SDL file from the CC version of Great Tree Pub. It wont be used again and it will probably only be used for references if the puzzle in the GTP is ever revamped.

[dpogue]

working on adding comments to the SDLs

Something to be aware of with SDL files is that every new change (adding or removing variables) requires copying and pasting the entire block of SDL declarations as a new version. If you're including inline comments in the file, those will probably also get copied/pasted each time.

That potentially becomes a performance consideration, because right now the SDL files on MOULa are downloaded in full on every launch of the game, and I don't believe there is any file compression (SDL files would compress wonderfully with GZip since they're a lot of duplicated text, but I don't think that's used here).

[Attagoat]

Possible solution to this, Could we have an internal SDL with the documentation just for us that doesn't get published to the actual game?

[dgelessus]

Perhaps it would make sense to document everything in a single block at the top of each .sdl file, rather than inside the block for each version? In addition to reducing the file size, that would make the documentation easier to maintain as new versions are added - though on the other hand, if there are significant changes between versions, those would be more difficult to document all in a single block.

That potentially becomes a performance consideration, because right now the SDL files on MOULa are downloaded in full on every launch of the game

That's a valid concern, but I think right now we don't have to worry about it too much. For shards that ship H'uru clients by default, it's generally not an issue, because the .sdl files can be (and usually are) provided via the file server, so they are downloaded in gzipped form and only redownloaded if they actually changed. It would be an issue for OpenUru clients, which normally redownload all .sdl files on every launch, but I assume the documentation comments won't be ported to the OpenUru repo, so they won't land on Minkata or in the deliveries to Cyan.

If large comments in .sdl files become a real practical problem at some point, I'm sure we can build a simple minification tool that automatically strips out comments and unneeded whitespace, which could be used to reduce the file size of .sdl files before they are deployed to a production shard.

[Deledrius]

It would be really great if Cyan could enable compression on the file transfers. :( Oh well.

[dgelessus]

By the way, some of the SDL files are also duplicated in another location (Sources/Plasma/PubUtilLib/plSDL/SDL). A while back I submitted #1254 to resolve that, but that was never merged (we might have all forgotten about it, heh).

In any case, all of those duplicated .sdl files are less interesting to document anyway. They're used by the engine itself to synchronize avatars, clothing, kickables, etc. - they don't belong to any specific age and you can't set them as global SDL settings.

[Hoikas]

Something to be aware of with SDL files is that every new change (adding or removing variables) requires copying and pasting the entire block of SDL declarations as a new version. If you're including inline comments in the file, those will probably also get copied/pasted each time.

Tangential, but something to consider here is that we have the SDL for many Ages since before GameTap and even before ABM. These older state descriptors could safely be deleted from the SDL files because it seems... highly unlikely that anyone has an SDL blob on their shard that from before the initial open source release. In short, we should consider deleting all state descriptors prior to the most recent versions from the initial release.

[Attagoat]

Age SDLs will be done first, I'll worry about non-age SDL's later