Open, human-readable minesweeper video format

Area to discuss development and bugs of official clones (Clone, Arbiter, MSX, Viennasweeper)
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Open, human-readable minesweeper video format

Post by Cryslon »

UPDATE 2021.05.26 - Version 6 released at github.com/thefinerminer/minesweeper-rawvf

Draft for open RawVF format.

Revision 5.

Syntax:

Code: Select all

<video> ::= <description> <board> <events>

<description> ::= <option> <description> | <option>
<option> ::= <optionname>: <optionvalue>\n
<optionname> ::= {non-empty string without :}
<optionvalue> ::= {string}

<board> ::= Board:\n <grid>
<grid> ::= <row> <grid> | <row>
<row> ::= <mine><row> | <safe><row> | <mine>\n | <safe>\n
<mine> ::= *
<safe> ::= 0

<events> ::= Events:\n <eventlist>
<eventlist> ::= <event> <eventlist> | <event>
<event> ::= <mouse_event> | <board_event> | <game_event> | <scrolling_event>

<mouse_event> ::= <elapsed_time> <mouse_event_id> [column] [row] (<coord_x> <coord_y>) [(<mouse_state>)]\n
<elapsed_time> ::= <second>.<hundredth> | <second>.<thousandth> | -<second>.<hundredth> | -<second>.<thousandth>
<mouse_event_id> ::= <left_click> | <left_release> | <right_click> | <right_release> | <middle_click> | <middle_release> | <mouse_move> | <left_click_with_shift> | <toggle_question_mark_setting>
<left_click> ::= lc 
<left_release> ::= lr 
<right_click> ::= rc 
<right_release> ::= rr 
<middle_click> ::= mc 
<middle_release> ::= mr 
<mouse_move> ::= mv
<left_click_with_shift> ::= sc
<toggle_question_mark_setting> ::= mt
<mouse_state> ::= [<left_pressed>][<right_pressed>][<middle_pressed>]
<left_pressed> ::= l
<right_pressed> ::= r
<middle_pressed> ::= m

<board_event> ::= <board_event_id> <column> <row>\n
<board_event_id> ::= <number> | <unopened>
<number> ::= number0 | number1 | number2 | number3 | number4 | number5 | number6 | number7 | number8
<unopened> ::= closed | flag | pressed | questionmark | pressedqm | blast

<game_event> ::= <elapsed_time> <game_event_id>\n
<game_event_id> ::= start | boom | won | nonstandard

<scrolling_event> ::= <elapsed_time> <scrolled_axis> <position_horizontal> <position_vertical>
<scrolled_axis> ::= sx | sy
Proposed options:

Code: Select all

 RawVF_Version: version number of RawVF format
 Program: clone name
 Version: version name
 Player: player name
 Timestamp: date and time
 Level: level name
 Width: board width
 Height: board height
 Mines: number of mines
 Skin: skin name
 Mode: classic/lucky/density/upk/cheat
--- settings ---
Marks: question marks on/off
--- cheat settings ---
Lives: number of lives
Autoflag: auto flag squares which are known mines on/off
Lawnmower: flag all mines on first click on/off
ElmarTechnique: left click as left click+left release on/off
NonoMouse: mouse movement with pressed button counted as click on/off
SuperClick: left click on opened square as chord on/off
SuperFlag: right click on opened square as autoflag on/off
--- protection ---
Checksum: 
Revision 4 changes: columns and rows are made optional, added two new events needed to represent MVR video.
Revision 5 changes: added optional board events, game events and scrolling events, added optional mouse state to mouse events, allowed negative elapsed time and a checksum option.

------

This format is meant to become a standard for non-protected minesweeper video. I hope once we'll enjoy tools translating all binary protected formats in RawVF. The advantages are great: with such tools one could write a universal video player and other programs counting different stats from videos stored in different formats. And we'll be able to do this independently from inconsistent clonemakers who tend to appear and disappear suddenly.

Eg: MyClone doesn't have WastedClicks counter, but there's a tool translating .myclone to .rawvf. You're able to write your own WastedClicks for .myclone, and you don't need to have long conversations with MyClone author.

Please make your suggestions. I promise to release avf2rawvf complying with the agreed standard, and i hope all other clonemakers will follow.

avf2rawvf - converts Arbiter's AVF to RawVF revision 5
mvr2rawvf - converts MSX's MVR to RawVF revision 5
rmv2rawvf - converts ViennaSweeper's RMV to RawVF revision 5
mvf2rawvf - converts almost all Clones' MVF to RawVF revision 5
rawvf2rawvf - writes board events into RawVF
Last edited by Cryslon on Mon Jul 29, 2013 3:50 pm, edited 22 times in total.
Go IRC! (try mibbit)
Mucleus
Posts: 7
Joined: Tue Dec 02, 2008 1:58 pm

Re: Open, human-readable minesweeper video format

Post by Mucleus »

Yes please, this would be awesome :) I don't quite understand the notation used, but anything easy to read would obviously be fine. Would it be better to use the game time elapsed rather than timestamp in events (and have game start time as another row).

Also, will it be possible to have a Recorder to txt program? I don't know if Sorin is still around :P Or whether the file structure is known.

And also e.g. 2 we'll be able to have pretty statistics for arbiter :)

EDIT: Should the file ext. be txt? It would be a pain trying to group files if they couldn't be distinguished.
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

I meant elapsed time by timestamp :)
Mucleus wrote: Also, will it be possible to have a Recorder to txt program? I don't know if Sorin is still around :P Or whether the file structure is known.
I haven't Sorin's coordinates. Same for Rodrigo, i can't communicate with him. Don't know how hard is it to reverse-engineer that crazy binary, but right now i have no time for it.
Mucleus wrote: EDIT: Should the file ext. be txt? It would be a pain trying to group files if they couldn't be distinguished.
Hm... Maybe .rawvf (Raw Video Format) ?
Go IRC! (try mibbit)
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

Code: Select all

<optionvalue> ::= {string}

Code: Select all

<optionvalue> ::= {string without newline}
;)

Otherwise, nice work! Looks good. no time to post much atm.
Don't anthropomorphize computers - they don't like it.
Mucleus
Posts: 7
Joined: Tue Dec 02, 2008 1:58 pm

Re: Open, human-readable minesweeper video format

Post by Mucleus »

Cryslon: not knowing virtually any C, I don't know how big an issue this is, but isn't giving the source to avf2txt vastly reducing the obscurity of the avf format?
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

@Tommy: hehe, of course all strings are strings without newline.

@Mucleus: i don't think releasing source makes AVF any less secure. avf2txt doesn't read all fields of AVF, it only reads board and video events. Board just jumps into your eyes when you look at AVF in hex editor, and to re video events of AVF isn't much difficult task too. I also strongly dislike idea of releasing programs without source code.
Go IRC! (try mibbit)
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

Anyway, the only real obfuscation needs to take place in the checksum. Viennasweeper has very straightforward vids that way too. If I have time I might write rmv2txt.
Don't anthropomorphize computers - they don't like it.
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

Tommy wrote:If I have time I might write rmv2txt.
Go & write it, what's the damn problem? :evil: If the format is truly straightforward, it should take ~15 min.
Go IRC! (try mibbit)
User avatar
abiu
Posts: 26
Joined: Mon Dec 01, 2008 3:01 am
Location: Ningbo, China
Contact:

Re: Open, human-readable minesweeper video format

Post by abiu »

How about KML format that is used in Google Earth, Maybe someday we can replay vids on google earth :)
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

abiu wrote:How about KML format that is used in Google Earth, Maybe someday we can replay vids on google earth :)
Well, the nowadays question is how to get all necessary info from those crazily made binary formats. If you have txt, you're able to do with it anything you want, since it contains all pieces of video information.
Go IRC! (try mibbit)
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

Are there any clonemakers ready to code something? Or this project is destined to die? :(
Go IRC! (try mibbit)
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

I'm currently in military service, so when I actually have access to a computer I'm usually too tired to code. After next week, though, I'll have a bit more time at least - possibly much more.
Don't anthropomorphize computers - they don't like it.
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

A relatively quick and dirty python implementation of the rmv converter is in progress and almost done ;) I'll post it here when I'm done and might provide a web-based converter (upload file -> download txt version).
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

Tommy wrote:A relatively quick and dirty python implementation of the rmv converter is in progress and almost done ;) I'll post it here when I'm done and might provide a web-based converter (upload file -> download txt version).
Very nice! Rodrigo was on IRC yesterday and hopefully we'll enjoy mvf2rawvf too... :geek:
Go IRC! (try mibbit)
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

Hi everyone, I have a proposal that will account for a relatively important change to the nature of the format.

While implementing rmv2rawvf, I noticed that there was a property of rmv - there precisely because rmv was intended to be usable as a universal format - that this format lacks. It seems unnecessary at first, but has many advantages.

The idea is not only to save mouse events, but also board events - thereby also storing the way the events are processed by the clone that makes the video, and implying that the player doesn't have to figure out what to do under certain circumstances (every clone has it's own idiosyncracies, like not handling middle mouse buttons correctly, and the player would otherwise have to take that into account).

This means that converters will have to emulate the clones event processing behaviour, in most cases. However, it also means that the player doesn't have to implement clone-specific behaviour for n clones.
Also, I propose termination events (events that tell the player that the game is over). Mostly unimportant, but can take into account games that terminate in a nonstandard way (for example, a clone unexpectedly shuts down).

The new grammar specification I want to propose is here:

Code: Select all

<video> ::= <description> <board> <events>
<description> ::= <option> <description> | <option>
<option> ::= <optionname>: <optionvalue>\n
<optionname> ::= {non-empty string without :}
<optionvalue> ::= {string}
<board> ::= Board:\n <grid>
<grid> ::= <row> <grid> | <row>
<row> ::= <mine><row> | <safe><row> | <mine>\n | <safe>\n
<mine> ::= *
<safe> ::= 0
<events> ::= Events:\n <eventlist>
<eventlist> ::= <event> <eventlist> | <event>
<event> ::= <mevent> | <bevent> | <termevent>
<mevent> ::= <elapsed_time> <mevent_id> (<coord_x> <coord_y>)\n
<bevent> ::= <bevent_id> <column> <row>\n
<termevent> ::= gameover <termtype>
<termtype> ::= boom | won | nonstandard
<mevent_id> ::= lc | lr | rc | rr | mc | mr | mv
<bevent_id> ::= <number> | <unopened>
<number> ::= number0 | number1 | number2 | number3 | number4 | number5 | number6 | number7 | number8
<unopened> ::= closed | flag | pressed | questionmark | pressedqm | blast
<elapsed_time> ::= <second>.<hundredth> | <second>.<thousandth>
Don't anthropomorphize computers - they don't like it.
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

By the way, so that everyone can imagine how this is supposed to look, this is an example:

Code: Select all

opt1:val1
opt2:val2
Board:
00*0
*000
0*0*
000*
Events:
0.301 lc (7 8)
pressed 0 0
0.323 mv (9 9)
0.352 lr (9 9)
number1 0 0
0.457 mv (10 11)
0.539 mv (10 13)
0.598 mv (11 16)
0.681 mv (12 18)
0.724 mv (12 19)
0.786 lc (12 19)
pressed 0 1
0.817 mv (13 18)
0.834 lr (13 18)
blast 0 1
gameover boom
Moderators/Cryslon, fill in meaningful option/value pairs if you want to.
Don't anthropomorphize computers - they don't like it.
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

I wrote avf2rawvf.

It writes only mouse events and not board events. Reasons for this were:
1) i think we should separate these two tasks: one program (like avf2rawvf) takes protected format and produces mouse event stream in rawvf, and another program takes this mouse events and produces board events. Notice that first program could be written only by clonemaker since he is the only man to have knowledge about his protected binaries. The second program may be basically written by any person who owns the clone and may test its mouse events processing.
2) i'm pretty disappointed because of total lack of enthusiasm showed by clonemakers. Damn, it takes at most half an hour to write the convertor, and they're still too lazy to write even the light version.
Go IRC! (try mibbit)
CBright
Posts: 39
Joined: Sun Nov 30, 2008 11:53 pm
Contact:

Re: Open, human-readable minesweeper video format

Post by CBright »

Hey guys, I think this is a great project and know there has been some desire to watch/analyze *.mvr files in other clones. Therefore, I am making mvr2rawvf available as a command-line windows executable.

Usage: mvr2rawvf input[.mvr] [output] [player]
For example, to convert all mvr files in a directory to rawvf files you could run:

Code: Select all

for %f in (*.mvr) do mvr2rawvf "%f" "%f.rawvf"
The way the timestamps are reconstructed may be slightly off. Since the final timestamp can't be considered 100% accurate, I included a "Time" header.

During implementation a number of issues arose with the format:
  • Minesweeper X records events before the game officially starts, but there is no way to specify a time for these except 0.000.
  • Events off of the board are also recorded; these are listed with (column, row) = (0, 0).
  • Minesweeper X allows the marks option to toggle during a game; I used a "mt" event for this.
  • It also allows a shift-left-click, which acts like a left click when the right button is pressed; I used a "sc" event for this.
  • However, there is still no way way to actually specify which buttons are pressed during events: you can't assume that all click/release events were recorded, as the program may have lost the focus when they occurred. (For the original Minesweeper the only relevant states are the right button state during a left click, and vice versa, but other programs might need more.)
  • Actually, the original Minesweeper has a quite strange behaviour in that to unambiguously play certain unusual button press sequences you also need to record something about how the previous game ended!
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

CBright wrote:I am making mvr2rawvf available as a command-line windows executable.
Nice! :) Could you make a Linux binary also if you don't want to release the source?
The way the timestamps are reconstructed may be slightly off. Since the final timestamp can't be considered 100% accurate, I included a "Time" header.
I tested the thing on several exp videos and noticed that the longer video, the bigger the gap between actual video length and last timestamp. On my 54 gap was 0.2, on 71 seconds gap was like 0.5 seconds, i think it's pretty large and disturbing. Maybe there is some way to fix the thing?
Minesweeper X records events before the game officially starts, but there is no way to specify a time for these except 0.000.
IMO, 0.000 is OK. Do you think we need sth special?
Events off of the board are also recorded; these are listed with (column, row) = (0, 0).
OK. Maybe these row and column should be excluded at all from the format...
Minesweeper X allows the marks option to toggle during a game; I used a "mt" event for this.
It also allows a shift-left-click, which acts like a left click when the right button is pressed; I used a "sc" event for this.
Mhm. Added to event list.

... Do we need also "sr" for this?
However, there is still no way way to actually specify which buttons are pressed during events: you can't assume that all click/release events were recorded, as the program may have lost the focus when they occurred. (For the original Minesweeper the only relevant states are the right button state during a left click, and vice versa, but other programs might need more.)
Actually, the original Minesweeper has a quite strange behaviour in that to unambiguously play certain unusual button press sequences you also need to record something about how the previous game ended!
You're saying that the generated rawvf may be invalid?

I'd suggest some workaround for this occasion, like adding fake clicks necessary to bring mouse into needed state. IMO, it would be bad to change the format radically, eg adding mouse state to each event line...
Go IRC! (try mibbit)
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

I've said it before and I'll say it again... seperate mouse and board events! This is exactly what I meant - even if the board events should be redundant, they really aren't, and they don't really hurt either.
Don't anthropomorphize computers - they don't like it.
CBright
Posts: 39
Joined: Sun Nov 30, 2008 11:53 pm
Contact:

Re: Open, human-readable minesweeper video format

Post by CBright »

Cryslon wrote: Nice! :) Could you make a Linux binary also if you don't want to release the source?
I was thinking of that, as I myself run Linux, but really, you can just use wine mvr2rawvf. ;)
Cryslon wrote: I tested the thing on several exp videos and noticed that the longer video, the bigger the gap between actual video length and last timestamp. On my 54 gap was 0.2, on 71 seconds gap was like 0.5 seconds, i think it's pretty large and disturbing. Maybe there is some way to fix the thing?
You're right, I suppose it is disturbing. I updated the program so it doesn't let round-off errors propagate. However, the thousandths digits should really be considered approximations.
Cryslon wrote: IMO, 0.000 is OK. Do you think we need sth special?
Probably not, unless people really want to watch the mouse movements before the game opens.
Cryslon wrote: OK. Maybe these row and column should be excluded at all from the format...
They may be useful to a human reader, but otherwise unecessary. Well, actually, you should make sure that everyone agrees where the (0,0) coordinate is.
Cryslon wrote: ... Do we need also "sr" for this?
No, the original Minesweeper (and almost certainly all clones) don't need that. Actually, a somewhat surprising fact is that the original doesn't even need to know what button is released; it only needs to know that a button is released.
Cryslon wrote: You're saying that the generated rawvf may be invalid?
If a click event occurs but is not recorded then a video based on the rawvf may not play correctly.
Cryslon wrote: I'd suggest some workaround for this occasion, like adding fake clicks necessary to bring mouse into needed state. IMO, it would be bad to change the format radically, eg adding mouse state to each event line...
Technically, this wont be enough. There's a bug in the original Minesweeper where right clicks act like left clicks, but this can only happen when the left button is pressed and its click event was not recorded.
Tommy wrote:I've said it before and I'll say it again... seperate mouse and board events! This is exactly what I meant - even if the board events should be redundant, they really aren't, and they don't really hurt either.
The important thing is to get the mouse events, since the board events can be reconstructed from them. Besides, that reconstruction is really a (nontrivial) job in its own right, since it basically requires simulating Minesweeper and the click handling logic. I hope to do something like this eventually.
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

Tommy wrote:I've said it before and I'll say it again... seperate mouse and board events! This is exactly what I meant - even if the board events should be redundant, they really aren't, and they don't really hurt either.
The problem is: at least AVF and MVF don't contain any board events. So your approach will force convertor writer to code entire minesweeper click processor. And we can't even get from clonemakers the lighter version of convertor. So, your suggestion is maybe good but apparently unpractical.
Go IRC! (try mibbit)
Cryslon
Posts: 130
Joined: Sun Dec 28, 2008 7:41 pm

Re: Open, human-readable minesweeper video format

Post by Cryslon »

CBright wrote:I was thinking of that, as I myself run Linux, but really, you can just use wine mvr2rawvf. ;)
It's not straightforward. What's the problem with compiling it for Linux?
Technically, this wont be enough. There's a bug in the original Minesweeper where right clicks act like left clicks, but this can only happen when the left button is pressed and its click event was not recorded
Hmm... I think it's not necessary to reproduce all the original bugs.
Go IRC! (try mibbit)
CBright
Posts: 39
Joined: Sun Nov 30, 2008 11:53 pm
Contact:

Re: Open, human-readable minesweeper video format

Post by CBright »

Cryslon wrote: It's not straightforward. What's the problem with compiling it for Linux?
For one, I'd rather only have one update one file. I can send you a Linux version if you want.
Cryslon wrote: Hmm... I think it's not necessary to reproduce all the original bugs.
Fair enough; but faking button presses properly still requires that you know something about click processing, which was something I thought this format wanted to avoid. Maybe I'll start using "sc" to also mean "right click with left pressed" when the left press wasn't recorded; that should allow proper playback, but makes "sc" ambiguous as to what button was pressed. As far as behaviour is concerned, sc=mc, although that is semantically invalid.
User avatar
Tommy
Posts: 257
Joined: Mon Dec 01, 2008 9:22 pm
Location: Vienna

Re: Open, human-readable minesweeper video format

Post by Tommy »

CBright wrote:
Tommy wrote:I've said it before and I'll say it again... seperate mouse and board events! This is exactly what I meant - even if the board events should be redundant, they really aren't, and they don't really hurt either.
The important thing is to get the mouse events, since the board events can be reconstructed from them. Besides, that reconstruction is really a (nontrivial) job in its own right, since it basically requires simulating Minesweeper and the click handling logic. I hope to do something like this eventually.
Cryslon wrote:
Tommy wrote:I've said it before and I'll say it again... seperate mouse and board events! This is exactly what I meant - even if the board events should be redundant, they really aren't, and they don't really hurt either.
The problem is: at least AVF and MVF don't contain any board events. So your approach will force convertor writer to code entire minesweeper click processor. And we can't even get from clonemakers the lighter version of convertor. So, your suggestion is maybe good but apparently unpractical.
I'm not saying that a file format containing only mouse events is a bad thing to do in principle, but I would use it as an intermediate format that may also be bypassed.

The idea is more or less the following:

There are two file formats, rawvf and truevf (stupid name, I know, I'll call it tvf, feel free to backronym it to something that sounds better).

rawvf contains mouse events and a unique identifier for the clone that the video was made on (or a group of compatible clones - arbiter43, arbiter44, clone 97, clone20x, for instance). There is a converter that uses this identifier to infer which clone-specific converter to invoke (this is a shortcut, but storing the information makes the file contain all information necessary to replay the game. There is also a generic converter that is used if no converter for that file format exists.
Converters produce tvf, tvf contains mouse events and board events, it may (but does not have to) also include the identifier of the clone that the game was played on, in any case, it is trivial to write a program that can replay these video files (hey, wo could let tvf stand for that ;)).

Why two file formats?
Both have their places. Clone makers may only want to supply a converter to rawvf, and the effort required to convert these files to tvf is very low (the generic converter might even be enough). With tvf, it is easy to consider to just evaluate the board events at runtime instead of implementing a new file format. However, I see a couple of reasons not to do this:
1.) It seperates the converter and the video player, making the whole process less bug-prone
2.) For some clonemakers, it makes a LOT more sense to convert to tvf straightaway (ViennaSweeper for instance, reconstructing the board events that were already there in the original video is an insanely stupid thing to do, in my opinion)
3.) The two file formats can be very similar, to the extent that tvf could be just rawvf with one header value set differently, and more information.
Don't anthropomorphize computers - they don't like it.
Post Reply