[Feature]: TFS project: where to keep documentation?

[gesior]

By submitting this feature issue, you agree to the following.

• [X] There is no existing issue for this feature (or similar) already

Pull Requests or Links to add this feature

No response

Request

What do you want to achieve?

• one project documentation used by everyone that covers all topics (compilation, TFS code/features)
• documentation forkable with project (downgrades etc. will contain ex. how to compile engine)
• up to date documentation: update with PR, you can update C++/Lua code and documentation in same commit

Right now there are 2 documentations:

• GitHub wiki: https://github.com/otland/forgottenserver/wiki - hard to update (only TFS maintainers can?), not up to date
• docs project: https://github.com/otland/docs - not mentioned anywhere? not up to date

Why? I'm planning to add new feature to TFS ex. "binary items save". It will store items in new SQL table in custom binary format. Acc. makers that show EQ of player will need to read that format from database. It would be much easier, if in commit with C++ changes I could add documentation of that format and how to read it.

My idea Create folder docs on Git with documentation in MD format. Only text, no images (to do not increase project size too much).

What do you think about it?

Possible Solutions

No response

[luanluciano93]

very good!

[ArturKnopik]

Good idea!

[Zbizu]

regarding binary save, I suggest changing the way the system serializes the items

current problem is similar to OTBM - the engine is being told (in sources) how many bytes have to be read so if it faces unknown attributes (eg. loading the database after revert of some upgrade/imbuement system), or even an item that is no longer a container in the otb, it results in a corrupted read. While this never happened to my server in production (due to proper management), it happened a few times in my local test environment.

[gesior]

current problem is similar to OTBM - the engine is being told

That's how it works in my new binary save. In earlier version I've saved all items in tree structure (parent/child Container etc.) with no information about attributes length. It made binary data unreadable on website and single bugged item attribute could break all player items. Now I save it in same format as relational data in database columns:

		itemsStream.write<uint32_t>(runningId);
		itemsStream.write<uint32_t>(pid);
		itemsStream.write<uint16_t>(item->getID());
		itemsStream.write<uint16_t>(item->getSubType());

		itemsStream.write<uint32_t>(attributesSize);
		itemsStream.writeBytes(attributes, attributesSize);

so there are sid, pid, itemID and item with same bytes size for each item, and then there are attributes, but with uint32_t storing attributes lenght. So single bugged item attributes can be skipped and all next items can be still loaded. I've benchmarked it and it's only 5% slower then old format. Binary save is already 20x faster than relational, making it 5% faster won't change much and I don't think it's worth risking some players lose all their items.

I've also prepared parameters for already running OTSes to convert all player items to new format ex. ./tfs --convert-to-binary (or ./tfs --convert-to-relational if someone needs old format for some reason), but this format is so simple (100% like in relational DB), that you can convert it with ex. PHP script. PHP 7.1+ code to parse binary items:

• just items in slots, single PHP function (ex. acc. maker EQ page): https://paste.ots.me/564146/text
• just items in slots, using PHP class: https://paste.ots.me/564147/text
• read all items, then filter slot items from array, using PHP class: https://paste.ots.me/564148/text