Jump to content

Mod metadata - providing mod full name, description, readme files/links, download/update links


AL|EN

Recommended Posts

Hi,

let me start from make clear statement that NOTHING IS REQUIRED. Did I say that nothing is required? Yes, that's true, nothing is required. You don't have to do anything. My proposition/design also aims for be "less selfish as possible" aka "don't require anything and if, require minimal amount". I hope that's clear now.

The main idea behind this is to give back the control of mod metadata in the hands of modders. Which person know the current and most up to date mod name, description or the working link to the place where players could receive support? That's right, the modder itself or current maintainer.

The first idea was to have a website where modders could provide mod metadata. Creation of such website is very simple and can be done in one day. But then there is a problem when some other people will provide 'malformed' info about other people mods. Trolling is an art. It's impossible to counter without some sophistic login/verification method. And ofc "yet another website" will be instantly boycotted, even if it would be offer a Genie in a bottle.

So without website, similar to "mod configuration file", a mod could provide few important metadata like:

  • full name of the mod itself, without version number
  • general mod description
  • improved alternative for README keyword - you can also put direct links to online readme's
  • link to mod dedicated forum or forum thread
  • link to mod persona homepage if exist
  • direct download link to the latest version of the mod

This is my take on this matter:

0. File encoding: It can be ANSI if it won't contain Unicode strings. UTF8 (no BOM), if you want to use local language characters.

1. File format of such file must be 'industry standard', one for all mods. And please forget about xml :p I can't write a custom parser for each mod only because it's author like to put spaces before and after '=' character. Or use TAB to separate key and values. Or include weidu commands which only WeiDU can parse with it's GLR parser. It would be too much work. So let's choose one, modern 'industry standard' file format. My vote goes for INI as a first choice.
 
2. File extension of 'mod metadata file': Almost irrelevant, follow the file format definition associated extension. Those files shouldn't be modified by players anyway.
 
3. Filename of such 'mod metadata file'. There is one, very simple solution: <modTp2name>.ini. This is what is currently implemented.
- it doesn't require file header / ini sections added [Mod] require [Metadata] section header to avoid false detection
- it prevents people from making multiple, outdated version of this file
 
4. File content: nothing is required, you can even put one, single line Key=value pair with only mod full name. The INI will have preference over data from tp2.

INI:

# Never copy this from other mod, always use https://github.com/ALIENQuake/ProjectInfinity/wiki/Adding-metadata-for-mod
# Filename must be the same as tp2 basename, placed at the same folder where
# .tp2 file is located, use "UTF8 without BOM" encoding, everything is optional

# ini section header is required to avoid false detection
[Metadata]

# Full name of the mod, without the version number, without the list of supported games
Name = Mod Example - Optional Features

# Author name or nick, don't use an email address
Author = AL|EN

# Short description of the mod, main goals, features etc
Description = This mod is a guide on how to use optional 'Project Infinity' features.

# Web address of mod readme file (filename is case-sensitive!) You can link to txt, md, html, pdf etc.
Readme = https://example.com/ModName-Readme.html, https://example.com/ModName-Readme-%LANGUAGE%.html

# Web address of mod dedicated forum or forum thread 
Forum = https://www.example.com/forums/categories/forum thread

# Web address of mod personal Homepage, no need to duplicate with a mod dedicated forum
# Homepage = https://www.example.com

# if you use Github.com, simply use https://github.com/AccountOrOrgName/RepositoryName
# read more about Delta Updates https://github.com/ALIENQuake/ProjectInfinity/wiki/Delta-Updates-for-mods-hosted-at-Github
Download = https://github.com/AccountOrOrgName/ModExample-OptionalFeatures

Remarks:

If there will be a demand, PI could use JSON with comments file or JSON5/HJSON, it has very strict rules, only for modders who wan't to benefit from the advantages of the JSON file format itself. Order of the preference: JSON > JSON5/HJSON > INI . It means that if you provide only INI, everything works. Later, if someone wan't to switch to more advanced metadata format, mod metadata will be read from them. I think that INI would be enough but I don't want to limit modders.

5. Visual representation:
- mod metadata will be displayed inside "Mod info textbox"
- in addition, mod name will be displayed at treeview/mod list
- mod download link would be used to download new mod version (if it is supported)
 
rQNvqAF.png
 
If you have suggestions or questions, feel free to ask.
Edited by AL|EN
formatting, cosmetics
Link to comment

Where does the key "Information" point to for a mod that has a readme, a forum, and a website all hosted online, and not necessarily at the same base URL?

 

Also, if you mandate everyone conform exactly to "an industry standard", you must point to strict documentation of that standard. Preferably, the standard and documentation would be rigorously maintained by a recognized authority. Ideally, the format chosen would be established and widespread enough to be *natively* supported by many programming languages, and IMO be human-readable.

Link to comment

Where does the key "Information" point to for a mod that has a readme, a forum, and a website all hosted online, and not necessarily at the same base URL?

 

Also, if you mandate everyone conform exactly to "an industry standard", you must point to strict documentation of that standard. Preferably, the standard and documentation would be rigorously maintained by a recognized authority. Ideally, the format chosen would be established and widespread enough to be *natively* supported by many programming languages, and IMO be human-readable.

 

Ad 1.

It display the the value. So if you enter homepage, it will display homepage. You want three separate keys for online readme, online forum/post and homepage? No problem :) You have to define extra ini keys, I would need to add them to parser and "Mod Info box" it will display all of them.

 

Ad 2. Good point:

INI: https://en.wikipedia.org/wiki/INI_file

JSON: Definition https://www.json.org, Validator https://jsonlint.com/

JSON5: Definition https://json5.org/, it's just the same as JSON with possible comments and less rules, no online validator yet :/

HJSON: Definition: it's just the same as JSON with possible comments and less rules, online validator http://hjson.org/try.html

 

All of those formats are "human-readable".

Edited by ALIENQuake
Link to comment

It would be a very bad idea to write this on the assumption that [mymod].ini is metadata. Doing so would be to reserve a chunk of namespace inside people's mod folders that has no particular connection to the purpose (you can't tell from the fact that it's called [mymod].ini that it's metadata) and that conflicts with already-existing usage in at least some mods (notably SCS).

 

This is bad practice in an abstract space, but more importantly it runs a serious risk of false positives, i.e. of a file being parsed by your autoinstaller as if it's metadata (or, worse, configuration options) when it was not intended to be parsed that way by the writer. (If you had implemented this proposal without me being aware of it, you might well have ended up offering SCS's and Wheels of Prophecy's debug options to the end user as installation choices.)

 

If you want to do this (and it sounds sensible) then you need conventions whereby files only get treated as processable metadata if they are explicitly and intentionally marked as such by the mod maintainer (or, I guess, by a BW Fixpack change if we're talking about not-currently-maintained mods). There are lots of ways to do that:

 

1) My preferred option, as I said on the other thread, is to embed a keyword in the comment field of the file, as in

;;;IE_METADATA_FILE;;;
2) Alternatively, you could mark a file through a particular key-value pair, as in

treat_this_as_ie_metadata=1

3) If you really want to insist on doing this through namespace, pick a bit of namespace that you can be really confident isn't going to be used except for the intended purpose. metadata.ini is the obvious choice; using a .metadata suffix would also work. Theoretically this is less safe than either of the first two proposals; in practice I doubt you're going to get anyone who's already (e.g.) using "metadata.ini" to indicate something that's not metadata.

Link to comment
On 9/16/2018 at 6:06 PM, DavidW said:

It would be a very bad idea to write this on the assumption that [mymod].ini is metadata. Doing so would be to reserve a chunk of namespace inside people's mod folders that has no particular connection to the purpose (you can't tell from the fact that it's called [mymod].ini that it's metadata) and that conflicts with already-existing usage in at least some mods (notably SCS).

 

This is bad practice in an abstract space, but more importantly it runs a serious risk of false positives, i.e. of a file being parsed by your autoinstaller as if it's metadata (or, worse, configuration options) when it was not intended to be parsed that way by the writer. (If you had implemented this proposal without me being aware of it, you might well have ended up offering SCS's and Wheels of Prophecy's debug options to the end user as installation choices.)

 

You concerns about 'false-positive detection" are valid. I might have been gone to far in terms of "require nothing". That is why I wanted to receive feedback from modders. You "metadata.ini" is a good suggestion. The name reflects it's purpose. With one minor defect: It would be impossible to store multiple metadata files inside one directory. So how about <*-metadata>.ini ? So it could be "modtp2name-metadata.ini" but it doesn't have to be. The important pat is thee 'metadata.ini" part. I think it's very safe and no modder will create such file by accident.
 
As an alternative to you comment/key-value, how about using a INI "Section", let's call it [Mod] or [Metadata] inside the ini file of any given name, which will be inside main mod folder, where tp2 file is:
[Metadata]
Name=NPCs Enhanced for Everyone
Description=This is intended to be a successor to the fantastic "Level 1 NPCs" mod. L1NPCs was never updated for the EE games, and its author is no longer active, and it is an incredible, complicated piece of work that is difficult for someone else to update. So I made this.
Download=http://lynxlynx.info/ie/modhub.php?UnearthedArcana/NPC_EE

 

Such method can also be applicable to JSON/HJSON/JSON5.
 
I believe that combining those two requirements could be very, very safe and no false-positive detection could occur. Unless there will be a major opposition to use INI Section, and a clear message from other modders that "filename schema will be enough" I would like to go for it.
Edited by AL|EN
Link to comment

Ad 2. Good point:

INI: https://en.wikipedia.org/wiki/INI_file

JSON: Definition https://www.json.org, Validator https://jsonlint.com/

JSON5: Definition https://json5.org/, it's just the same as JSON with possible comments and less rules, no online validator yet :/

HJSON: Definition: it's just the same as JSON with possible comments and less rules, online validator http://hjson.org/try.html

 

All of those formats are "human-readable".

The wikipedia page for INI doesn't mention it, but I'm pretty sure any language relying on Windows API to read INI files will limit the length of a key's value to 65,535 characters. This presumably includes AutoIt (and so BWS) and AutoHotkey. Just a tidbit to keep in mind in the event of rather verbose descriptions...

Link to comment

Two metadata files can coexist to provide different kind of metadata: for a mod information and for mod dependencies ;)

 

I requested new keywords for tp2 long time ago. The wisp conclusion was that the tp2 code is not a good place for those information. Metadata files are much better suit for such data. Code vs Data separation: modification of the metadata it can be added/modified without touching tp2 file. They are industry standard, parser and tools are very solid etc.

Edited by ALIENQuake
Link to comment

In what case would a mod want to include more than one metadata file? Sounds like an unnecessary complication.

 

Since you're already parsing weidu — why not store all of it there, just like author?

Good question and my answer, of course, is that you wouldn't... well, perhaps in the case of Level 1 NPCs NPC-components, you could see it, as that's per NPC, but other wise, nope to me.

I intend for the file to contain all the variables I use as the inserts ... so it needs to complete as a weidu's .tpa file, which is just a part of a .tp2 injected in, so it needs to follow the regular .tp2 coding. Dah... which is what I refered in the above post.

We don't care if another program can get something out from it.

Link to comment

Still sounds like needless proliferation.

With a fixed name it's also always obvious what's inside (and less chances for misspelling/miscasing).

 

What problem does it actually solve? If the metadata is stored with the source, one always has to download it to check if it changed.

Link to comment

Still sounds like needless proliferation.

With a fixed name it's also always obvious what's inside (and less chances for misspelling/miscasing).

 

Well, that's valid too, but unless you convince DavidW, I need to keep "<modname>-metadata.ini" scheme.

 

 

 

What problem does it actually solve? If the metadata is stored with the source, one always has to download it to check if it changed.

 

The source of the mod metadata is the mod itself, not some external database.

Edited by ALIENQuake
Link to comment

 

Still sounds like needless proliferation.

With a fixed name it's also always obvious what's inside (and less chances for misspelling/miscasing).

 

Well, that's valid too, but unless you convince DavidW, I need to keep "<modname>-metadata.ini" scheme.

 

What do you need to convince me of? I'm neutral as to whether you need multiple metadata files or just one - going from "metadata.ini" to "xx-metadata.ini" was your idea. I'm also fine if you want to read metadata out of mymod.ini provided there is a completely unambiguous way to designate it as metadata that won't lead to false positives - your suggestion of using .ini section headers is less hacky than my ideas.

 

I don't think I'd seen "store the metadata in the tp2" mentioned before, but I'm strongly against it - code/data separation, please.

Link to comment

Join the conversation

You are posting as a guest. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...