Constructor Undo System - Managing Expectations
by Tom Bampton · in Artist Corner · 08/03/2006 (9:49 pm) · 5 replies
Since Beta 7 is just around the corner, I thought I would manage expectations a bit on what the undo system is capable of now, and where it's going.
Where the Undo System is now
Most importantly, not everything is undoable, and won't be for some time. The current undo system as of Beta 7 can only deal with brushes, and only the following actions:
* Selections
* Locking
* Hiding
* Grouping
* Creating and deleting brushes (provided the geometry does not change)
* Moving
* Rotating
* Scaling
Dave tied the tools system into undo for Beta 7, and thus changes to brushes through the tools will now be undoable. This was not the case in Beta 6.
If you include something that's not a brush (for example, a light entity) in a selection then move it, the entity will not undo with the brushes. This is not a bug, entities are not undoable yet.
I know it can be a pain in the backside to remember what's undoable and what isnt. Hell, I wrote the system and I still press Ctrl+Z for things that arent undoable. Partly because of that, Beta 7 now sports a shiny new undo form that works similarly to Photoshop's history list.
Black entries in the list are actions that you can undo, grey are actions that you can redo. You can click anywhere in the list to undo/redo directly to that point. The entry will appear in red if a snapshot has started but not ended yet; as will be the case when using some of the tools.
What happens when you undo while a tool is active depends on the tool. If you're using a transform tool, it will act pretty much as expected: the current snapshot will be cancelled, the last one undone and then the tool reactivated.
If you're creating a brush, undo will cancel the tool and then immediately reactivate it without performing a "real" undo.
The absolute best way to find out what's undoable in any specific beta is to read the release notes. If it's not mentioned in the release notes, it's probably not undoable yet.
Where the Undo System is going
This post is getting rather long, so I'll be brief here.
Barring any bugs in current code, the next items on the list of what to make undoable are Shapes, Entities, Texturing and Brush geometry.
The order in which this will occur depends a lot on when the undo system as a whole is ready to move on.
At some point during all this, caching of the undo stack to disk will be implemented. Caching the undo stack to disk will enable us to support an effectively infinitely extending undo stack, and will be implemented when undo memory usage requires it. As an aside, if you want to know how much memory the undo system is using, type tmu(); in the console. The numbers are in bytes.
Don't ask me for a timeline ;-)
Reporting Undo related bugs
Please, before you report an undo related bug - read the release notes and make sure that it is actually a bug and not something that's unimplemented.
The most useful way to report bugs in undo is to first find a simple reproduction case and include this with your bug report. Most undo related bugs so far have been reproducable by creating 3 brushes in an empty scene and doing whatever was necessary to reproduce the bug.
Since the undo system is based on incremental snapshots (only what has changed in the scene gets included in the snapshot), undo is a bit different to redo. Sometimes bugs only happen when you're undoing and not when you're redoing (or vice versa). This information is important for me to know to fix the bug.
Related to the above, if you undo/redo in by clicking in the undo form this is important to know - especially if it involved undo/redo through more then one snapshot.
Remember: The more information you can give, and the simpler the reproduction case is, the quicker the bug will get fixed. It is probably also a good idea if you talk to us on IRC in #constructor before reporting the bug on Mantis since the undo code changes daily and we may already have fixed it.
Where the Undo System is now
Most importantly, not everything is undoable, and won't be for some time. The current undo system as of Beta 7 can only deal with brushes, and only the following actions:
* Selections
* Locking
* Hiding
* Grouping
* Creating and deleting brushes (provided the geometry does not change)
* Moving
* Rotating
* Scaling
Dave tied the tools system into undo for Beta 7, and thus changes to brushes through the tools will now be undoable. This was not the case in Beta 6.
If you include something that's not a brush (for example, a light entity) in a selection then move it, the entity will not undo with the brushes. This is not a bug, entities are not undoable yet.
I know it can be a pain in the backside to remember what's undoable and what isnt. Hell, I wrote the system and I still press Ctrl+Z for things that arent undoable. Partly because of that, Beta 7 now sports a shiny new undo form that works similarly to Photoshop's history list.
Black entries in the list are actions that you can undo, grey are actions that you can redo. You can click anywhere in the list to undo/redo directly to that point. The entry will appear in red if a snapshot has started but not ended yet; as will be the case when using some of the tools.
What happens when you undo while a tool is active depends on the tool. If you're using a transform tool, it will act pretty much as expected: the current snapshot will be cancelled, the last one undone and then the tool reactivated.
If you're creating a brush, undo will cancel the tool and then immediately reactivate it without performing a "real" undo.
The absolute best way to find out what's undoable in any specific beta is to read the release notes. If it's not mentioned in the release notes, it's probably not undoable yet.
Where the Undo System is going
This post is getting rather long, so I'll be brief here.
Barring any bugs in current code, the next items on the list of what to make undoable are Shapes, Entities, Texturing and Brush geometry.
The order in which this will occur depends a lot on when the undo system as a whole is ready to move on.
At some point during all this, caching of the undo stack to disk will be implemented. Caching the undo stack to disk will enable us to support an effectively infinitely extending undo stack, and will be implemented when undo memory usage requires it. As an aside, if you want to know how much memory the undo system is using, type tmu(); in the console. The numbers are in bytes.
Don't ask me for a timeline ;-)
Reporting Undo related bugs
Please, before you report an undo related bug - read the release notes and make sure that it is actually a bug and not something that's unimplemented.
The most useful way to report bugs in undo is to first find a simple reproduction case and include this with your bug report. Most undo related bugs so far have been reproducable by creating 3 brushes in an empty scene and doing whatever was necessary to reproduce the bug.
Since the undo system is based on incremental snapshots (only what has changed in the scene gets included in the snapshot), undo is a bit different to redo. Sometimes bugs only happen when you're undoing and not when you're redoing (or vice versa). This information is important for me to know to fix the bug.
Related to the above, if you undo/redo in by clicking in the undo form this is important to know - especially if it involved undo/redo through more then one snapshot.
Remember: The more information you can give, and the simpler the reproduction case is, the quicker the bug will get fixed. It is probably also a good idea if you talk to us on IRC in #constructor before reporting the bug on Mantis since the undo code changes daily and we may already have fixed it.
#2
I think the best thing to do with already-posted bogus bugs is just post in the comments for the bug. With a couple of your bug reports, there did actually turn out to be issues similar to what you mentioned once those things were undoable - so bogus bug reports can occasionally be useful. If they do turn out to be junk, then someone with access to delete bugs can always do so later.
T.
08/04/2006 (3:08 pm)
I've already hit Mantis and posted comments in those bugs. There were bugs from a couple of people in there along these lines, which is what prompted this thread.I think the best thing to do with already-posted bogus bugs is just post in the comments for the bug. With a couple of your bug reports, there did actually turn out to be issues similar to what you mentioned once those things were undoable - so bogus bug reports can occasionally be useful. If they do turn out to be junk, then someone with access to delete bugs can always do so later.
T.
#3
Great job! Can't wait to play!
08/04/2006 (9:39 pm)
I love the history pane concept. That was one of the most intuitive pieces of Photoshop that was added back in the day. Is there a way to access the history pane through script? I am thinking of taking common "history items" and creating something like an actions pane in Photoshop for common actions. Having access to a list of things that "worked" in the history would be a great boon to working with an action system. Great job! Can't wait to play!
#4
The undo history form in Beta 7 is just a first pass proof of concept that Dave and I threw together to see how well it would work. It's likely not very extendable/reusable as it stands.
On the other hand, the information that is used to populate the undo history is available in script through the undo manager. Unfortunately, the script side of the undo manager is currently completely undocumented (including through dump()) so that may not help you so much.
We will be improving the undo form in a later beta - don't ask me which one, I don't know yet ;-)
T.
08/05/2006 (3:27 am)
If this post reads like crap its because ive been awake for far too long.The undo history form in Beta 7 is just a first pass proof of concept that Dave and I threw together to see how well it would work. It's likely not very extendable/reusable as it stands.
On the other hand, the information that is used to populate the undo history is available in script through the undo manager. Unfortunately, the script side of the undo manager is currently completely undocumented (including through dump()) so that may not help you so much.
We will be improving the undo form in a later beta - don't ask me which one, I don't know yet ;-)
T.
#5
08/05/2006 (7:17 am)
Well, I'm downloading now so I'll play a bit, undocumented or not. I always thought that it would be a neat feature in a map editor since I often find myself doing repetative tweaks to make things "just right" over and over again. I'll see what I can come up with (most likely just a bunch of playing around, but that's part of the fun anyway!) 
Associate Dave Calabrese
Cerulean Games