Car archive

[Duplode]

Thinking about it, and a bit broader..
The wiki doesn't have a place as well (or I couldn't find it quickly and that's basically the same thing)

Can we make subgroups underneath wiki and portal sub?

Maybe, but I'm not sure if we need a sub-subforum for each part of stunts.hu. The use cases are different, and in some of them keeping a broader subforum might be clearer than splintering it into many smaller ones. In particular:

• For this car archive project, a specific subforum would be a good fit for specific design discussions that would be awkward to post in a unstructured megathread or among the car release announcements in the Custom Cars subforum. It would be similar for a track archive project once it gets started.
• For feature requests and feedback gathering about the Forum and Portal, I think the current Stunts Forum and Portal should be enough to cover them. We can explicitly add the Wiki to its description, and perhaps move the Stunts Wiki megathread there.
• As for discussions about Wiki content while working together in the articles, I feel they would be best done in the Wiki itself, which has support for such things and doesn't have the easy access issues that e.g. GitHub might bring. We can use the article talk pages for specific article discussions, and the Stunts Wiki namespace for meta issues or in-wiki project coordination.

[dreadnaut]

@Duplode I agree on keeping off GitHub for most discussions, for the moment, so I have disabled all the chatty features on the project. I could link instead to a forum section, but also happy to continue in a thread.

@Cas The example structure above follows YAML syntax. I'm not wedded to it, but my take is as usual to use a format that is already common and successful in similar use cases, rather than defining a new one.

Let's start with some fields then. The only required one could be name 🤔

- the four letter identifier is the file name, it does not appear in a field
- name: the name of the car
- nickname: a shorter, commonly used name
- author: main author, or should we have authors as a list?
- year: (or release_year or year_released) year of release of the first version with this 4-letter id
- colors: list of liveries, in showroom order
- urls: key-value list of related pages (e.g., stunts wiki)
- description: brief description of the car, should cover all versions with the same car id
- game_version: one of 1.0 | 1.1

Do we want a general statistics key containing things like flat_speed, top_speed or zero_to_sixty? Would empirical numbers sit separately from fixed ones like grip_value or gears_number?

[Daniel3D]

I would like general statistics.

Mass / PG class
Flat track top speed
0 / 60
0 / 100
Grip and/or Tire type? Track/Road/Rally
Car Class (race/sports/road/off-road/special)

These also provide good filter options.

[dreadnaut]

These also provide good filter options.

That's a very good point: filtering should be one of the main use cases.

[Cas]

I know YAML very generally. I should read the fine details about it. I think the most important thing is that it be easy to skip what one doesn't want to parse at the moment and that it doesn't get too complex. For example, escape characters complicate the format quite unnecessarily. This can be solved either using a format that does not use escaping or using a format that does, but avoiding the creation of files that use this feature. YAML has its drawbacks, like it takes more space than JSON. But on the other hand, it's much more readable by humans and I like it more.

I think we can add as many details as necessary, but the ones that are crucial for the internal car configuration, in my opinion, are title, author and release date. This latter would serve as a "version number" and I would recommend it be in YYYY-MM-DD format so that we can easily sort them by string order and quickly know which one is newer.

If there can be more than an author, I would say it'd be important to have one field for the main author called "author" and another for co-authors or something of that sort. The idea is that, when you want to read the author property, you know to expect a simple string and not have to deal with the possibility of finding an array. Just my idea.

On another, related topic. I'm working on another garage program, a more visual one, but this could be implemented for Simple Garage as well. The thing is I've been leaving room in the code for online repositories to be read by the program. While developing, I've realised of some things that would make it more straightforward to do this:

The easiest way to read a repository is to know that, at the given web path, there's a file with a fixed name, say "repo.yml", if it may, that contains a list of all cars available in that repository, for each item, containing at least the car name and the list of the file names that are included for that car. Then, when you want to actually download the car, what you do is look for those files in the same directory and curl them down. They could be the individual car files or a single zip file containing them. In the latter case, we should agree on the zip file name, for example "car<ID>.zip", like "carcdor.zip" for the Melange, so that the program can recognise it. Any more ideas can be built on that.

This way, the program reads the repository list once at the beginning and doesn't need to scan it again for each car.

About JSON... I've said before I don't like it because it's difficult to parse and it's true, but of course, this is especially true for the general JSON format. You can always have a certain JSON file have a more specific format that follows JSON, but that can be expected to be much simpler. There's also XML... probably the least optimal of the three. Anyway, I'm just throwing my ideas. Let me know what you guys think.

[Duplode]

- author: main author, or should we have authors as a list?

I think it's important to record multiple authors. There usually (though not necessarily) is a distinction between a main author and other contributors, and keeping track of it through separate fields, as @Cas suggests, could be semantically reasonable. (Also, it's indeed appropriate for the author to be optional, as sometimes we just don't know who they are.)

[dreadnaut]

Re authors, I think single author plus a list of contributors should cover most cases, and provide a simple format.

Regarding the discussion on formats and syntax, I would prefer not to go into that now. In my mind the archive is not meant for direct consumption by tools, but should be optimised for people. It's a folder curated by a group of people, sort of a wiki. It should be easy to write.

It should be machine-readable though, so that we can build any number of fronts. One of them produces a format that garage tools can read, another is a searchable website, etc. That way, we don't have to choose one format that all tools ever need to be happy to. And we are not tied to GitHub as a service or similar. It could all run from your hard drive.

So my focus right now is "what data do we need to collect, and what's a simple, well supported format to type it in". I'll start lining up the fields we've discussed above in a schema. A question in the meanwhile:

I can think of different type of values for a car:
- those part of the car definition (e.g., powergear behaviour, transmission gears)
- those that need to be measured (e.g., zero-to-sixty)
- arbitrary labels that need agreement (e.g., "race car" or "rally")

Do we want to include all of these? Do we want them separate in the structure? (e.g., characteristics vs statistics) Can you help me list them and group them?

[Daniel3D]

- author: main author, or should we have authors as a list?

I think it's important to record multiple authors. There usually (though not necessarily) is a distinction between a main author and other contributors, and keeping track of it through separate fields, as @Cas suggests, could be semantically reasonable. (Also, it's indeed appropriate for the author to be optional, as sometimes we just don't know who they are.)

Something similar with car colours.
Some are Multi colour. But usually there is a dominant colour.
So for that maybe a primary colour and a secondary colour.
Where the secondary colour can be set to multi.
That should include most colour schemes.

[dreadnaut]

Something similar with car colours.

To be honest, I hadn't thought full descriptions of each paint jobs would be included. I assumed rough labels like "Red/Blue" or "Red stripes" would be enough 😅

[Cas]

I like the idea of the machine interface not being central in it. I had thought maybe other things in a car archive during, say, web browsing by a user, would make use of a central file that would also be used for the exchange, but now that you say this, I think your approach is better.

About categorising the properties, my personal opinion is that it should be possible to see properties as all the same level, but they can have a non-essential category. Let me explain what I mean with something stupid, but clear. Say you have a car and that car has a name, but the car has an author and that author also has a name and so does it's colour. So you could have something like:

car
+- name
+- author
|  +- name
+- colour
   +- name

Then here "name" doesn't give you any clear property. You have to specify car.name or car.author.name or car.colour.name. So author and colour are essential categories of name. On the other hand, you could have many properties that each is unique and you can get to just as easily ("get to" meaning "call it", if human read or meaning "obtain it", if machine read or maybe other verbs), but maybe each property also has a property of its own that's its category. That'd be a non-essential category, because it's under and not on top of the property definition. Damn!  So simple ideas are so long to explain!  Or maybe it's me, who can never say things in a single sentence    Anyway, hope it makes sense.

[Duplode]

Something similar with car colours.

To be honest, I hadn't thought full descriptions of each paint jobs would be included. I assumed rough labels like "Red/Blue" or "Red stripes" would be enough 😅

Yup, I'd lean towards that as well: settle on "standard" names for common paint jobs, and, on a case by case way, use simple combinations or invent fantasy names for the uncommon ones. I might start a thread for collecting those later 

[dreadnaut]

One more question, and a difficult one: how would we store a car that has both a 1.0 and a 1.1 version, with the same car id?

A few options I can think of:

- No no no, the archive is only for 1.1 cars
- Mmmh, should we have two separate archives?
- Two root directories?
- Append the version if needed? So CDOR, but PMIN-1.0 and PMIN, or similar?
- Two versions under the same car-id directory? Like PMIN/1.0 and PMIN/1.1
- Very few cars have a 1.0 version, handle that as an alternative version, and consider 1.1 the default? E.g. PMIN/ and PMIN/stunts-1.0

At first look, I think I prefer the last one, but I'm looking for feedback.

[alanrotoi]

How do I make my cars for 1.0 versions?

[Duplode]

One more question, and a difficult one: how would we store a car that has both a 1.0 and a 1.1 version, with the same car id?

The last option is probably good enough. The arrangement that would feel more natural to me, though, would be game_version specifying the primary version of the car while allowing it to be overridden by an optional version field in a separate, version-specific file. (That's assuming such a version-specific file would be useful for other purposes, so we wouldn't have to add it just for that.)

How do I make my cars for 1.0 versions?

We currently don't have a good way of doing that, but in principle it's something we could solve with some more investigative work. The problem is that the 3SH format in 1.0 (1990 Broderbund) is different, so you can't just use your 1.1 custom shapes directly. That said, recent versions of dstien's stunpack can uncompress packed files from 1.0, so we might try unpacking a P3S, seeing what the format differences are, and writing a converter. (Cf. the work done on converting cars to the Amiga version.)

The opposite direction is usually less of a problem: since old-school 1.0 cheat cars invariably borrow graphics from the original cars, converting is just a matter of replacing the graphical files with their 1.1 counterparts. (The original cars, in fact, are the ones which require a closer look in this context: notoriously, the Indy torque curve was changed from 1.0 to 1.1, and AFAIK we haven't verified whether anything of the sort happens for other DSI cars as well.)

[Daniel3D]

Something similar with car colours.

To be honest, I hadn't thought full descriptions of each paint jobs would be included. I assumed rough labels like "Red/Blue" or "Red stripes" would be enough 😅

Yup, I'd lean towards that as well: settle on "standard" names for common paint jobs, and, on a case by case way, use simple combinations or invent fantasy names for the uncommon ones. I might start a thread for collecting those later 

Number of paint jobs. Handy for live races..