From 487074a6b566b2769d9401083879239a99c609c4 Mon Sep 17 00:00:00 2001
From: adelikat <adelikat@users.sf.net>
Date: Sun, 30 May 2010 23:45:55 +0000
Subject: [PATCH] Better document new loadstate logic and fix up changelogs

[[Split portion of a mixed commit.]]
---
 src/movie.cpp     |  64 +++++++++++++++++++++++++++++++++-------------
 vc/Help/fceux.hnd | Bin 226187 -> 226239 bytes
 2 files changed, 46 insertions(+), 18 deletions(-)

diff --git a/src/movie.cpp b/src/movie.cpp
index 17bfe47a..f3dd74a6 100644
--- a/src/movie.cpp
+++ b/src/movie.cpp
@@ -1278,27 +1278,55 @@ bool FCEUMOV_ReadState(EMUFILE* is, uint32 size)
 		return false;
 	}
 
-	//complex TAS logic for when a savestate is loaded:
 	//----------------
-	//if we are playing or recording and toggled read-only:
-	//  then, the movie we are playing must match the guid of the one stored in the savestate or else error.
-	//  ---the savestate is assumed to be in the same timeline as the current movie.---
-	//		adelikat: correction: the savestate timeline should not be assumed, because a read-only desync is still potentially destructive
-	//			playing from a desynced state, making a new savestate, and loading it in write mode will destroy a movie, and it isn't always obvious that there is a desync
-	//  if the current movie is not long enough to get to the savestate's frame#, then it is an error. 
-	//  the movie contained in the savestate will be discarded.
-	//  the emulator will be put into play mode.
-	//if we are playing or recording and toggled read+write
-	//  then, the movie we are playing must match the guid of the one stored in the savestate or else error, give the option to load it anyway.
-	//  the movie contained in the savestate will be loaded into memory
-	//  the frames in the movie after the savestate frame will be discarded
-	//  the in-memory movie will have its rerecord count incremented
-	//  the in-memory movie will be dumped to disk as fcm.
-	//  the emulator will be put into record mode.
-	//if we are doing neither:
-	//  then, we must discard this movie and just load the savestate
+	//complex TAS logic for loadstate
+	//fully conforms to the savestate logic documented in the Laws of TAS
+	//http://tasvideos.org/LawsOfTAS/OnSavestates.html
+	//----------------
+		
+	/*
+	Playback or Recording + Read-only
 
+    * Check that GUID of movie and savestate-movie must match or else error
+          o on error: a message informing that the savestate doesn't belong to this movie. This is a GUID mismatch error. Give user a choice to load it anyway.
+                + failstate: if use declines, loadstate attempt canceled, movie can resume as if not attempted if user has backup savstates enabled else stop movie
+    * Check that movie and savestate-movie are in same timeline. If not then this is a wrong timeline error.
+          o on error: a message informing that the savestate doesn't belong to this movie
+                + failstate: loadstate attempt canceled, movie can resume as if not attempted if user has backup savestates enabled else stop movie
+    * Check that savestate-movie is not greater than movie. If not then this is a future event error and is not allowed in read-only
+          o on error: message informing that the savestate is from a frame after the last frame of the movie
+                + failstate - loadstate attempt cancelled, movie can resume if user has backup savesattes enabled, else stop movie
+    * Check that savestate framcount <= savestate movie length. If not this is a post-movie savestate
+          o on post-movie: See post-movie event section. 
+    * All error checks have passed, state will be loaded
+    * Movie contained in the savestate will be discarded
+    * Movie is now in Playback mode 
 
+	Playback, Recording + Read+write
+
+    * Check that GUID of movie and savestate-movie must match or else error
+          o on error: a message informing that the savestate doesn't belong to this movie. This is a GUID mismatch error. Give user a choice to load it anyway.
+                + failstate: if use declines, loadstate attempt canceled, movie can resume as if not attempted (stop movie if resume fails)canceled, movie can resume if backup savestates enabled else stopmovie
+    * Check that savestate framcount <= savestate movie length. If not this is a post-movie savestate
+          o on post-movie: See post-movie event section. 
+    * savestate passed all error checks and will now be loaded in its entirety and replace movie (note: there will be no truncation yet)
+    * current framecount will be set to savestate framecount
+    * on the next frame of input, movie will be truncated to framecount
+          o (note: savestate-movie can be a future event of the movie timeline, or a completely new timeline and it is still allowed) 
+    * Rerecord count of movie will be incremented
+    * Movie is now in record mode 
+
+	Post-movie savestate event
+
+    * Whan a savestate is loaded and is determined that the savestate-movie length is less than the savestate framecount then it is a post-movie savestate. These occur when a savestate was made during Movie Finished mode. 
+	* If read+write, the entire savestate movie will be loaded and replace current movie.
+    * If read-only, the savestate movie will be discarded
+    * Mode will be switched to Move Finished
+    * Savestate will be loaded
+    * Current framecount changes to savestate framecount
+    * User will have control of input as if Movie inactive mode 
+	*/
+	
 	if(movieMode == MOVIEMODE_PLAY || movieMode == MOVIEMODE_RECORD || movieMode == MOVIEMODE_FINISHED)
 	{
 		//handle moviefile mismatch
diff --git a/vc/Help/fceux.hnd b/vc/Help/fceux.hnd
index 904357928c775704cae4af3813c2389f6a792968..a871cb1c3318717b1c5360ae553503290fb91f5f 100644
GIT binary patch
delta 5251
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
QK`n0>Jyaev^@d&iA8dYH@&Et;

delta 5185
zcmZ9QWmuH$)5bRdQI=Rz1PKWdge3$C=|)&ky1TnnKv<NPmRLeSBp0L}!6if_B&0z=
zQaYqt#7F+?#&Nvw!<YTdoHOTK*S+kAxm(uAW7o*Zb?$?SXaN8KDPS_YxrW?O2#ooB
z=P1NQiiJc8RU#}*N_UcA;f+!>85a0;<St{u%h(uK+-Ds_jm;SO?Gj@_BM=3`!pT#A
zFcv&Q&v6;IFn%aD^D1>6mx)4l;+%B~8gWC(OVe>uaak&Ex^xW<Zm4eKHC&C?M_mZk
zr}N7d+%ZN+9^;C&CL3@=FV7m_&SSHvgag#tWgOIP1>$Oi_kQ7K!45}pKz#BLS7UM>
zf`z(ipbh!oS!g*5AcO`>+U!6wtO44b6F7-I5?bOG5QVE-5d%71!q(}?06DQH=*Nmc
zAM8ERTX5hLT!*7BFcEtT^qD1)8b=gvKvSIR<^^=a(X<~hMF8vPT>vb_&1EhD+6!ZI
z;gi5$*qfuD%>&JF9rMe;M>sOx0NUfu(z*v+ru^GcR|;CdnZyx+I!MVese2=pw2cQ4
z0Dv87P7V@Bz?pmKIuTbXS%PR*Y+#8=)VBP6!qvuAX|be~oem6wHr34!Zg7dtj)~Oy
zJ+5mkbG&M)6cBE<3O%?Q@N8yH=mdI@Q?_#kWV+jtP;J#%{^NJv?knA;<K0p%)Bet1
zG*hpS#X`>VzIz0p&!)teY>TDmj&Scw{fS>&x@#_#fUtkJ-z7yxM(Hu*s~vSCIkq=S
zQd>#WAa}CJJjdkpWZ+Sy(g(q&{hj-_6w*!xJsX$a--fBIW+t>pNL|0a`FqEPN;Z~E
zLN$MwKQN4sT7tHHpE<dRb@@r*;n362j)!(9Z=>~fpvG4g!O5;U1Ifm}KdK44AVRx+
z>?}(1`)m<uUtSE%vV|ny&zxILIh|8<I~=8I>e5>;(ty<$+-ri2PSr|L<+F$;__*6!
zrNNOc-BHFn>!~nAE9{ZoZTI6<!{4hv`*$o{>^yprWWHOhI|f@DN|Q$L2%~#Ya8C5J
z`7wO%>65i)mL}E?Qz@yEy!-W+nrId>Hb*Kep~{H72@A_DxYB|5DKKB4V`YubRiL8D
zpfJC?z3A|t0LzeoHR)%8?k+9AdFn{=I8N_zJwl66H6)+x{JY)0GnXd?Lnk&3Y7e~o
zspt2hlv0Mj0Y*>1>h;){<T1ibJgSK@QAyxeLpMq8$~Mig2<0ky-PdGPS_5R)y{jyb
z`$;1r2*!HlqES+4@F<(H7||S@uo2&na)>?m;julOSFyEJc|=*MvE2_tKGydrD~ULN
z>sT(_8n(kqk=r~~6<57QZ>cfH`Yl^l>YIy%K<upd$mrhK?G@x24>(2J-a^KsPbBNz
z@ukVzkNuMQGDq{7*~y@<-@E$KA`>W97W+LBkJpIBn>0gPW?IsVPv@RrpAb1@0lv@c
zyX>`@M}}1M+T6_>`iB1Fd#fD5|1`w+yGf&WCaEmUOnaJ-@psdG<=0FTGz-lntY%++
ztao0t&R^8)g}2Ps=e}nZ`PtTPi1JhON$t&lSrGL2guQ)W8;1DTbK|wM?ZIK;q*DP?
z1tK>)9u2l;WgOo<4X+a$AD<3Ud{;B+f(AG+)haWMJ+sx5x3*JrbUX@9)|i@cS`xje
zz3c4TxNjFK$}QI*t3dyO=b__B(r`?nQlae+x?sgmiqzIlJZT&+3agb9w4T9*f$Lo5
z*NZCXw~Ib#d#7>Rt9Pg%X=5Qr^1AJq-yfrf@F!O~lw6@0%S8gZ)ur&|?R3ae8??t~
zw*8%Pfl<@@3{7tP`qgjq&IYeVZ#t?+t#~Bs2E{r+riRr)jq4ZF+l=jp+SwD<g~l|V
zQS7vudP$pZudU&_c9{eG8*wYH!_&_+)r&z770Ng)rj#0}fAS4gKq4Xz-k!CFt02th
zm<0rh>gG@om(MS?DB4R?=`=-|8JxcD<v@B@cqT3rzY+Yv-W|dCb*0YSNLo%+ZF5<F
zz(z>L#$6&iq+Ni1EM3oZ?XDOgUhl;YWCto8{$QQ6&!2het;V~yaXL1raiqw0iCu@z
zwR%ehlt_lmpy(QnvSdkGj@gTFig1Lyf63S`YgMQ<g_O}on->>|?QM4Gr6{@|@hIP!
zd@HuF(MF#wp7xJ^Q<d6ELbUX7QX&&=j=-t!Lz)7jOqZA^iZ@X1n%^gEe=$}dEObK0
z#vKl`e0J!)@8uTrT&+CX(=aJSB^Xd8-7uSQzE`P5^$p;Z5BWF1WtjURPro>VyxSUT
z+L|Pgq|sd?l1-*0&c@&}Eq~V7t?)C7ze9Z$2{vbQ*OUCZpOh0B6DVF>Po;OYK}B}M
zo4d`x(j@U}n|17=Z+YeXz;_zK`6129SKkvz1oac0Lgm7k`Jg`25W9NNYY5lgoi<Z3
zMQx%IySD><kT~8HnSW>j&5RKU^Mjkh!)M<%iS3GV!*w$NVsdKoaIKPRi0N1Tm>0_M
z2gxMNIvF3gGQ#t(PinmgTT2*-U5hf;kx$=vC6BHQ;W6>^JIZ=v1eh3o=p+v2NX#G8
zxevRLD-7=Wn5qsXE3fJ9`cTNxIZ@vcvVeI2e68|O2+x7l0vvuz9(Iaw$XXgRabFw?
z`xSkch{i`#6$*y)a6ITpH+XOc=;`#8S62RXBPgdJwpMVI^E;<fb!o-uoaTvl2irw)
zQbVq0?Gbx8@20dFcXSr4YVS+7<Md|04rE07>0EGNWC=ZkkCaa5Xtcj`?JW+Op2<IB
zJcduoo;v#yQNyOylb+Wg{&A2INl}WtGQB9|`#i`>zLt!mRjNku^YT0y6rNJu&R6b8
zT2&lMq<!igI}`|{4|QK&76<}yTlu%JN@*JELw+r8pI_tduI}lu%4kdZv9p!J5sp~9
z$H#0ZUPh`-d{{DK$jX^*^|NwQ;}YPAPHR4jlR>JRxF?y8T~YD?!DyWxE2lyctlJqx
zBG>X}q+2w{#V9wDx-<IYE0;C@O0(q~RBgf;NzWbR(r+Bz>y;_4{4M7xsX!$q{Rk*K
zXlGeeDdp|Fc~13!7^K*^Fwp(vZ5EO4p@M|MSXRIsOvyaC-d=8VEz|oZ5!pxI3gy^#
z|6`%@9Z3$@8wUPzDuh9CKC1VN{)qbL6ZREed2Su(f@avuEuA!==sXiY`ol%wv@9dV
zA2xxX;%%DsbVmZb?{3?dLV6>(B}r6V=spz<>~4+bN0X_;rQP~z?O><9L%N>1o2Sw&
z?Wr`?RTU_ahh)pgYO9jw74iCG@{dkCrjHW~SZb4W;%b63%Mg6I5c{X`DKtW+ji)p-
zQPGU#v|mW?-7!}T+qkn&0TiVBVsB-_DZO#+Gf2_i;>59zd=^HF=3;Do^Q6uuj)9aS
z&gO#&zqK6K>7-QCt6*XGxF0~yJ2spxjRli#eFF1;By<@H0s4|5`+fV8yai^eaB+0D
z-;a|gApeF=5h26|&C7`S819G*Zt7*~=-fc|=O8Uv-k52vF@tMq!R($r;fHa9RjaC0
z4uksH*Yo84SGaE=D*HbC!yxJwak+4UOH5mx(q2Zcjy=j&%@@MP`=U^HDrm;K=cuR(
zY0qB1y%$i)!#`6J2RWvaOG}2r8H-&bvn;GD1U4Ox1K1F@mJY%nXNMy8xf;%(u`S2G
zYSKc|9W1$iQndk*>(n#DsnNYMr>Ar|vkY#bYR4$vJyQ7R)0=^*>Egk0`!%tVj6l($
z6TO6HcH?K!yOHar%ju@?mmm&?GH-0{x9AFsD5lJ$YM{Ou)_to>UFbHFx|>I6_@E}q
zJ+7L|oP&rb%h1SrZPUZXbT+mI!B3t)a?Zn<m1V(J)Y8(o&qW|i>d9Yo0}^iLWUzgF
zyx(*4r-hpFAb*nn!z{kct#AE2q)O1uKUuJT`!mgw>qKAatf<dDy10J2Y--0ic8R4s
zK0lxCa)r0VF24SEs9`hCilktv?aP&$W;B8P-o2?3h^e{L6pElzFNY&kPFzk-@SQZT
zO-W@BfmIdmL!_Kr<frd`az=e30nY@iqg5{vmsW+o3c282iq%wMM$8xgy4Cl5o_fZX
zG%-*5d+)KX59wgYKtS#T8TPWST$z+Q(O2kf-4yQGspuxog&-AH?Hern!~hZ_mVa)J
zp$|&ugAiZ3D-|i6vl;dscIG@)pF`uOKU7!cu1`})17Lq1>F#L}>)JU>PYo5YvQ#t(
zZp9p>CP>Z*uTSZFJzhN6_^fP@rP$b-5%9W^k*=|<*MjtZh1sWep|cEhyI(}IFB4n9
zOE%$N6`*41boBM>;m#D696%~{>E$Ok%uCrn*=-}@yxRA|GkF$DqQo{*>wzTNdW;lH
z3XFeb5}VxLMy|TvmCsrwZt0tdMIOZEwx9e$9L;|rb3fLwPiS<^33RJKUDeaq3W;A>
z%h8-z&m1qgj6hLUCfCZxid&KCHuNfHLCUxG2h?~MbFVb~+A#?=OXJgR45=G)GxHFz
zL_9?_JBw913YOF^CsTQxOZqVsFpC05SA+QE;9qtqiVWjc{rskX986V?^cwhzcO_2P
zbhSqyzNyjzeaCfHh2d9T`E>70h0<(C`k+%_OWM7IN0D7zp6(~Izr?c0O9O>vv}gS^
z)l|yIn{x%eODAeL^|_iQ1?aAhgxU)yJYGlqiG7ah9g<+npi*_0rGE8oM=EOjlfHZm
ziC{*<LuWAo$~cCq)2#T-&ta#-G2=DBM`1d|Pjw{QjVSMahU|0}UFc*gc!Bw7{<w7h
zEN3#d*nbcpv0<CXp`O>4?3J+?a%Wk%{rj!DoLQ<)Aw)m&+_Owje0RCDwxyLdN1mPz
z@gQ0|)2Cm7?+P_5CF$^z;U(Ip=>gF{!nb-p^!o8SkG<9|Ix8Pk=c0xitBt>SskL~y
z{cA3JbN<x^+lGOP2sN<rd#8|e^^RK#ZF~07KEg~rMZ}kr;u&v0k{YzUSYPIr+5=N)
zRkoPrncVnzPxrn5Yjfpj2M^S^Q{eWB>M(u6Zd}e%R{RC%|1HYs&(}cexU~w(3bMqJ
zF9(Pmw@rm{gQRe|R$fpF9d<c0lmkiO)~_^G&@Xyy?xh8&8oSP-m7PFjIMVe7>Ee1(
z{-8)fY@Kj1XaT#EqUli}S=@?eR0UGNEtEO6pb_jkhxX|J?c;hKdO$|F1+{esl#E+9
z_18f^aV|QWpmR9Z87>KSzJjGjCGY{xx#~VR9ovCaGX#tM6_L*j!NypaC4htxK9fd(
zeFA71<0TXUh)wVrYXUSAfYB5$`4eE60Q_cnDTV+m1dun!OF0BMBY?gIUaBDgxg|d1
zOn}b>V7J0c!33BjfT%TIN+!TI0n}~qQV{`ww)l)W0U8KEXNQ-(3D8e~TlRP<f&dEy
zkaoaJnFKf{zyn9TR6&5tPWX&H0a^)g-5D<h5MYb|LN0hI9s~bb{SRHh+N^)y2GFKx
z@d1bcfZZzqfB@z-5$=x-^AV1;b_Gjg|0(ia!A#&G77&u16$C@>xPq}SFp&RZ(m-J(
zqZ_`=*bNgaApJ2h)*D$o;GjVV0F3MW*E<wBOlX3-W18rZ{O))Y_rI|oGKLWM{EZ(V
zS1>Ww6qr-_ri~N;NZ|OdDG^fM18?%o1Jgu}%pt_He`6=)86lSN1T%s5i;xDM;Ct+U
zAH%i9U6vDK06>W9zpi7YAS5>mb8TKD{I&Nn%|HeuxfgzzmKWyfnAL)i6}A7j424Mp
zg^-^yW!Qrc?>W~~(f|N?u>X$WLb7|~y{x@4UZFD}<nRo}tI``kvKf;G(jq4bWsE+U
zGRjR5(rObw5<5bUhW8B{=8H^a`0ogEWU>!_#4x587=YX+#QeS(FOU0RWXpXp3>oMP
NrUDWpV|~GQ{s*DEXs7@H