Stunts Forum

We need to start somewhere: https://github.com/dreadnaut/stunts-cars/

Comments, suggestions, thoughts: everything welcome! ;D

I had been thinking of auto-generating car images viewed from the side to make a graphical garage, but had not considered SVG. It would be a nice thing to have, as the same image could be used for many things. My idea was to just generate a large bitmap, then scale it down to average colours and produce a softer image.

I don't understand most of the concepts in the idea, but it sounds cool! :)

What about adding the txt file in resources as info####.txt or info####.nfo
in this case infoCDOR.txt

And an multi platform accepted thumbnail image.
Img1CDOR.bmp.. (or tif, gif.. whatever is most convenient for programmers)

That way the car files are extended to 6 and include metadata and an image (or a few).
And can be used by other tools, like car managers.

Quote from: Daniel3D on November 10, 2023, 12:31:19 PMWhat about adding the txt file in resources as info####.txt or info####.nfo
in this case infoCDOR.txt

In my mind the archive is not meant to invent a new standard, that we cannot (and should not) impose on car makers, but to work with whatever they create — be it 30 years ago, or today. I think this is where tools that can generate images from the car files come in. Structured data would also live outside the car files, in the archive itself.

Part of the plan is a front-end to the archive itself, that can make data and images available in a consistent way:

- car makers make cars as they prefer
- the archive collects them and compiles details
- front-end generates images and offers a standard interface (e.g., zip files, previews, etc)
- tools can talk to the front-end and download data or files

Simple Garage does support a very basic additional car file. I think it's CAR*.CFG, but I don't remember. If it's not there, everything works as usual. If it's there, you can specify the author and version number. I would have to check back on the code to remember the details.

An interface for a car archive does sound great indeed. Lots of integrations and exchanges can result from that :)

After adding a first car I'm starting to think that Markdown might not be a good idea. Yes, one can write free text, but a free text description would be a minor part of the archive. The most important information for each car is structured data: author, date, powergear yes / no, colours, etc. A brief description could be one of this attributes. This brings it closer to @Cas configuration files, and indeed those could be generated automatically.

The main bit would then be something like this:
---
name: Melange XGT-88
nickname: Melange
author: Alan Rotoi
year: 2013
colors: [ Blue, Red, Yellow, Light Grey, Brown, Black, Green, Purple, Striped ]
urls:
  wiki: https://wiki.stunts.hu/wiki/Melange_XGT-88
description: |
  Alan's much-loved machine is a timeless classic with a long and proud
  history in prestigious contests. It is an IMSA pipsqueak with more than a
  few twists to spice it up.

With more attributes to come of course (suggestions?) and structure to be defined. But this feels like a more productive direction.

Combined with the SVG images...

My idea was. If you make a database with additional information. Make it so that there are flexible uses for it.
Like a resource/database for other programs or the wiki...

I still miss download links in the wiki, and in cases like Melange it would be cool the link to different versions.

Quote from: Erik Barros on November 11, 2023, 03:08:39 PMI still miss download links in the wiki, and in cases like Melange it would be cool the link to different versions.

I'll add my cars. They're already in a free access google drive.

Ok added the download links from every car page and in the list of custom cars:

https://wiki.stunts.hu/wiki/Custom_cars#List_of_custom_cars

@dreadnaut - Yes, Simple Garage's config files are super simple, a lot more basic than that. I think they use the equals sign instead of the colon, but other than that, they're pretty much the same idea. As they have not been used much, I could follow your standard for the next version for exchange

Next steps:

Find a decent initial set of car attributes
It will change over time, but it's helpful to consider use cases early. For example, the Custom cars (https://wiki.stunts.hu/wiki/Custom_cars) page in the wiki has a few interesting column. What should the website for the car archive show?

Add a few cars to the repository
To road test the structure, in particular for cars with multiple versions.

Set up a rough web front
This can sit under stunts.hu/cars or similar. A simple list of cars, and links to download them, to prove that the repository data does what we need.

Write down a definition of the structured format
So that other websites can produce similar data, and tools can consume it.

Add all the cars! 💥

Sounds great!  Decentralised is better, like, same basic structure ("protocol", but more like directory structure and perhaps GET query, at most, something simple) and so you pass a base path or domain to a tool and it can browse or download from any car repository.

So car IDs, I guess, we keep using the four letter system that's default in Stunts. In other words, same four letters, same car, except version in any case. Right?  To follow DOS, it should be case-insensitive and most ASCII wouldn't be allowed. Safest is letters, numbers, and underscore. Daniël recently introduced the number sign. In DOS, extended ASCII was allowed, but this brings problems for new Unicode based systems. What do you think?

Also, would a repository be able to have several subdirectories, like several "garages"?

Your config file example is interesting. It allows for multi-line values and is multi-dimensional. Just checking on this idea to make sure we understand it the same way:
* Pipe as the first significant (non-space) in the value side of the colon means multi-line
* Lines containing no colon are ignored except as part of a previously defined multi-line value
* A line with a colon provides a key:value pair and breaks any previously open multi-line value
* Identations allow for nested key:value pairs
Am I right?

Here my only doubt is how to handle when you need to enter a colon as part of a text. In my older configuration format (with equal signs), an equal sign is allowed in the value because only the first one separates key from value, so not allowed in the key. I was also just ignoring indentations.

I imagine these two could be internally seen as identical:
default_color: blue
urls:
  wiki: https://wikiaddress
  author_site: https://authorsite
author: Overdrijf
default_color: blue
urls.wiki: https://wikiaddress
urls.author_site: https://authorsite
author: Overdrijf
Just some thoughts

EDIT: Another thing to consider... how about lines that begin with spaces? I would like a simple format that looks good to the human eye, doesn't need escaping, is easy to parse, yet powerful. I can think of some opitmisations :D

Meta question: should we have a sub-subforum for this project? While my first impulse would be raising specific design questions and the like on GitHub, it's not likely everyone will be there to talk, and so keeping the discussions here would make sense.

Quote from: Duplode on January 20, 2024, 12:20:32 AMMeta question: should we have a sub-subforum for this project? While my first impulse would be raising specific design questions and the like on GitHub, it's not likely everyone will be there to talk, and so keeping the discussions here would make sense.

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?

Stunts Forum & Portal

Anything about the Stunts Racing Portal

www.stunts.hu and this forum

Making subs below

• Forum
• Portal
• Wiki
• Repositories
• Car Database

~~~

• Track Database?

Quote from: Daniel3D on January 20, 2024, 08:47:56 AMThinking 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.

@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 (https://yaml.org/) 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?

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.

Quote from: Daniel3D on January 21, 2024, 09:00:18 PMThese also provide good filter options.

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

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.

Quote from: dreadnaut on January 21, 2024, 08:00:42 PM- 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 (https://forum.stunts.hu/index.php?topic=4088.0)) 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 (https://zak.stunts.hu/articles/who-created-the-coconut-cars).)

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?

Quote from: Duplode on January 22, 2024, 06:32:34 AM

Quote from: dreadnaut on January 21, 2024, 08:00:42 PM- 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 (https://forum.stunts.hu/index.php?topic=4088.0)) 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 (https://zak.stunts.hu/articles/who-created-the-coconut-cars).)

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.

Quote from: Daniel3D on January 22, 2024, 02:13:09 PMSomething 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 😅

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 ;D   Anyway, hope it makes sense.

Quote from: dreadnaut on January 22, 2024, 07:48:10 PM

Quote from: Daniel3D on January 22, 2024, 02:13:09 PMSomething 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  :)

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.

How do I make my cars for 1.0 versions?

Quote from: dreadnaut on January 22, 2024, 11:54:17 PMOne 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.)

Quote from: alanrotoi on January 23, 2024, 05:04:01 AMHow 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 (https://github.com/dstien/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 (https://forum.stunts.hu/index.php?topic=4105.0).)

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.)

Quote from: Duplode on January 22, 2024, 09:23:17 PM

Quote from: dreadnaut on January 22, 2024, 07:48:10 PM

Quote from: Daniel3D on January 22, 2024, 02:13:09 PMSomething 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..

Uhm... I think we need to take the uniqueness (or lack thereof) of the car ID into consideration not only for the Stunts version. So far, we haven't had great problems with different versions of a car, yet there already is such thing. And I guess, other things could happen that break this uniqueness. While there are tens of thousands of possible car IDs, most of them are unlikely to ever be used (such as "9_#E") while others could spawn independently with ease, for example, if somebody outside the mainstream community begins building cars (think of "BLUE" or "CHEV").

I too feel more inclined towards the last option, but at this pace, with so many cars already, we should be thinking of "plating" our cars, ha, ha.

Quote from: Cas on January 23, 2024, 10:41:32 PMAnd I guess, other things could happen that break this uniqueness.

An example of a corner case: the Competition Car 0.85 used the PMIN ID, as it was meant as a substitute for the original Indy. In the Competition Archive, I dealt with that by changing the ID to CC08, in both the car files and the nine archived replays driven with it. (It's not obvious that such approach would be the best one in all kinds of possible collisions, though.) The Petrol Pete set of cheat cars (the ones that come with the Stunts 1.0 download at Kalpen) are in a similar situation: they were distributed as a set of RES files named like AARCOUN.RES, along with a batch script that would swap them with the files of the original cars.

Quote from: dreadnaut on January 21, 2024, 08:00:42 PMI could link instead to a forum section, but also happy to continue in a thread.

After thinking a bit more about it, I feel there's room for both of them: this main thread for general discussion, and a sub-board for wilder tangents and deeper dives into one aspect or another. That being so, I have created the sub-board (https://forum.stunts.hu/index.php?board=132.0) (and a thread to kickstart it  :)), while pinning this topic we're in to the Forum & Portal board -- let's see how well it'll work. (BTW, while the sub-board isn't that much out of the way, it might make sense to link to it from your opening post here.)

Not really sure what the best solution would be for the car IDs, but both Simple Garage and Pretty Garage (the one I'm working on now) heavily rely on standard four-character car IDs to identify cars, so once we have a good clear solution, I should see that they follow it... Hopefully, it wouldn't be super hard to implement.

Quote from: Cas on January 24, 2024, 07:40:51 PMNot really sure what the best solution would be for the car IDs, but both Simple Garage and Pretty Garage (the one I'm working on now) heavily rely on standard four-character car IDs to identify cars, so once we have a good clear solution, I should see that they follow it... Hopefully, it wouldn't be super hard to implement.

I think we should treat the ID as a number plate.

Quote from: Cas on January 23, 2024, 10:41:32 PMwe should be thinking of "plating" our cars, ha, ha.

That would also mean I think that we have to make an Registry for new plate ID's.
Were you can reserve an ID for your project for a set time (one year, renewable?) So if a creator disappears before it gets done the ID comes available again.

If an outside the community creation is found we have to determine case by case what to do about the ID if it's already in use.

Quote from: Cas on January 24, 2024, 07:40:51 PMNot really sure what the best solution would be for the car IDs, but both Simple Garage and Pretty Garage (the one I'm working on now) heavily rely on standard four-character car IDs to identify cars

Quote from: Daniel3D on January 24, 2024, 08:46:29 PMI think we should treat the ID as a number plate.

My two cents:

• IDs are, and should continue to be, the primary way of identifying a car. They are what the game understands, what pipsqueaks are used to, and what most tools work with.
• While IDs as number plates is a good mental model, and a good way to explain how they should be handled, I don't think that should go as far as we operating a registry, with applications and expiry dates -- too much red tape for dealing with too low an expected number of collisions.
• When ID collisions do happen, we might end up having to decide what to do on a case-by-case basis, though sketching some kind of procedure in advance might help. One possibility (this is not really a proposal, just floating ideas): once we learn about a car with the same ID of an already known one, add it to the archive with a changed ID (maybe modifying it according to predefined rules), and record the ID originally chosen by the author in an optional original-id field. (The archive interface might even have an user-facing option "Use original IDs, even if clashing", which would rename the files being downloaded.)
• Given the archive can help us with documenting versions and telling them apart, we might want it to offer complementary means of identification that go beyond IDs and consider the content of the files. Tool developers, generally speaking, wouldn't be expected to incorporate that into their programs (IDs would still be the baseline), but the information would be available if anyone wants to use it.

Quote from: Duplode on January 24, 2024, 10:18:55 PMThe archive interface might even have an user-facing option "Use original IDs, even if clashing", which would rename the files being downloaded.

The archive should at least give warning ⚠️.
If we accept doubling of ID's the Car managers have to be able to distinguish between them.
That would also solve the game version issue because adding that check is quite trivial considering. 
So adding a field to the car information could be wise, like.. | ID Double= (empty =Unknown) or Yes.
Downloading such car With a fake ID may be sensible, but shouldn't be mandatory. A car manager could do it as well, so the alternative ID and original should be stored as well.

Let's stick to identifiers as primary, unique key. We can handle duplicates when (if) they arise.

Beyond the methods discussed above, we can also rename the car, but add a alternative-ids property to list any aliased ones.

Quote from: dreadnaut on January 25, 2024, 06:58:53 PMLet's stick to identifiers as primary, unique key. We can handle duplicates when (if) they arise.

Beyond the methods discussed above, we can also rename the car, but add a alternative-ids property to list any aliased ones.

Yeah, that is (in the chaos of ideas in my head and the mess I've written down) the main thing.

We'll, I agree it's unlikely to come across collision. For the frequency of those events, we can perfectly handle them one by one. What we could do to make those cases less frequent is agree to try to avoid predictable car IDs for new cars.

For software development, it really is very comfortable to just rely on car IDs!  I can tell you that from my experience with the two garage programs. I've used that for R4K too, but the handling there is simpler.

A simple look-up table of known car IDs against their car names would be good too so when somebody wants to come up with a new ID, they can take a look there first. Not that it's a requirement, but I think it'd help.

Well then, I've put online a first version, and added three cars:

- https://stunts.hu/cars/CDOR
- https://stunts.hu/cars/ZGT3
- https://stunts.hu/cars/ZF40

I've converted the yaml files to INI to make them easier to consume by low-tech tools. I've dropped the descriptions: multiline and INI files don't get along, and it makes sense to keep the archive dry — the wiki can have a longer description.

That's really good!  It prevents unnecessary dependencies on third party libraries and reduces the chance of bugs on independently developed software.

Quote from: dreadnaut on January 27, 2024, 09:52:32 PMWell then, I've put online a first version, and added three cars:

- https://stunts.hu/cars/CDOR
- https://stunts.hu/cars/ZGT3
- https://stunts.hu/cars/ZF40

I've converted the yaml files to INI to make them easier to consume by low-tech tools. I've dropped the descriptions: multiline and INI files don't get along, and it makes sense to keep the archive dry — the wiki can have a longer description.

A description is also in the car file, so it can be provided if needed. At least, I assume that that can be coded into a website.