Having a SAVE feature in a project/game is one of the common things that could lead users to be more attracted and increase replay value for potentially recovering what was done in a previous visit. Using the SharedObject class in actionscript project/games is sometimes a requirement or at least a need, may it be AS1 (FP6), 2 or 3. It can be used to store valuable data like progress, settings, statistics, achievements and a lot more without dedicating storage on the server. Basically, SO or shared objects are like the browser cookies for flash, it is used to store some amount of data on the user machine, therefore it also has some limitations on its use (for security purposes really).

By reading the documentations or the livedocs, either for AS2 or AS3 (it’s really the same), you might have a gut start of what key points to remember.

• created shared objects can only be stored/retrieved on the same domain
• shared objects cannot be shared across domains, meaning a shared objects from “examplesite.com” cannot read shared objects created by another domain “mywebsite.com”
• users can disallow local storage per domain or opt-out globaly, then the object would not be saved locally
• data size to be stored is limited by which the user sets it (none, 10kb, 100kb, 1mb, 10mb, unlimited), although a dialog box can request an increase in storage if what is set is exceeded
• if the user sets a limit smaller than the shared object, the shared object would be deleted
• shared objects are stored on the user’s local machine not on the server, something shared over another machine cannot be accessed by another machine

The most essential part when using SharedObject is the SharedObject.getLocal() method, which is what we will be discussing more through out. Basically, AS1/2 and AS3 syntax haven’t really changed (although a few more rules were imposed in as3).

getLocal(name:String, localPath:String = null, secure:Boolean = false):SharedObject
[static] Returns a reference to a locally persistent shared object that is only available to the current client.

var mySo:SharedObject = SharedObject.getLocal( 'mySaveName', localPath, secure );
mySo.data.thingtoSave = myVariable; // your variables
mySo.flush(); // stores data into disk

Avoiding Known Issues

It might seem that using shared objects could be the simplest when you are only storing a couple of variables and objects like statistics or even could be the more complex when saving a game progress/state together with the players preferences. The bigger the system, more likely, the more complex your variables/objects are (same for games), and this is where possible issues during saving/loading/handling the shared objects.

Some common things to remember when using shared objects with your games:

1. Don’t use direct reference to objects and use the game’s data only not the actual game objects.
2. Use a localPath param on the getLocal() method.
3. Taking advantage of unique names for your shared object name.
4. Prompt and request for shared object size limit increase when your game needs it.

While I only have these that I can explain, you are free to share more if you have one or more. We can discuss and make the lives of other actionscript writers a little better.

Don’t use direct reference to objects and use the game’s data only not the actual game objects.

Why do I say this? Basically it is fine to store various data types such as objects and arrays on SO (shared objects), same goes for strings, numbers (int/uint), booleans and bytearray (as3). If you store references to local game objects on your shared objects, one way or another, your in for a later problem.

var mySo:SharedObject = SharedObject.getLocal( "mySaveName" );
// world.gameObject contains further objects like settings, player, etc
mySo.data.gamedata = world.gameObject;
mySo.flush();
// --

When you do something like the above, instead of storing the needed values only, you are referencing the local game object (w/c also contains references to other local game objects) in which Flash defines this as a copy of the local object but is really just a reference. Any change through out the game values/data would update the local object (which the shared object references) and Flash Player would write that into the shared object file when flush() is called or as soon as the shared object session ends – that is then swf file is closed.

The worst case here is that when you clear, reset or even delete your local game objects, the shared object which references to it will be affected and updated (as session has ended).

Also, even if don’t experience the possibility of issues when you do the above there, a problem might still arise when you load the shared object in later time. This case might not be so common but is possible to experience if loading the shared object is sloppily made. You can have inconsistent object references where the object contained within loaded shared object is conflicting, a duplicate, or not referencing the correct object.

A better and safest way of using shared objects (something like):

mySo.data.gamedata = {
  player:{
    score: world.gameObject.player.score,
    health: world.gameObject.player.health,
    currentLevel: <code>world.gameObject.player.currentLevel
  },
  settings:{
    mute: world.gameObject.settings.mute,
    quality: world.gameObject.settings.quality,
    particles: world.gameObject.settings.particles,
  }
}
/* well this is just a shortcut on containing them into objects,
 * but the point here is that score, health, currentLevel, etc
 * are all basic data types like number/int/uint, string, bool, etc</code>

Now you see that we store each valuable data only. We now transfer only the value of the variable not it’s reference. So while it’s fine to use objects and arrays on your shared objects, keeping be wary of how you do it, be careful.

You probably wouldn’t want to directly store instances of display objects, bitmapdata, functions, etc on share objects.

Use a localPath param on the getLocal() method

While passing the localPath parameter upon calling getLocal() is optional, although I would have to recommend using it by this time. In the case where you are building an independent system, prototypes, does not consider expansion/addons and will never be a part of a larger system, you can probably opt-out the localPath and never mind it.

So whats the issue of using and not using the localPath? By default, if you leave localPath by it’s default (null), it would use the the full path of the swf file (w/c includes the swf file itself) to store your shared objects.

#SharedObjects/<random code>/<domain>/<path>/<swf filename>.swf/<object name>.sol

• Windows XP and Vista:
  • For Web sites: %APPDATA%\Macromedia\Flash Player\#SharedObjects\<random code>\<domain>\<path>\<object name>.sol
  • For AIR Applications, %APPDATA%\<AIR Application Reverse Domain Name>\Local Store\#SharedObjects\<flash filename>.swf\<object name>.sol

• Mac OS X:
  • For Web sites, ~/Library/Preferences/Macromedia/Flash Player/#SharedObjects/<random code>/<domain>/<path from webserver>/<object name>.sol
  • For AIR Applications, ~/Library/Preferences/<AIR Application Name>/Local Store/#SharedObjects/<flash filename>.swf/<object name>.sol
• Linux/Unix:
  • ~/.macromedia/Flash_Player/#SharedObjects/<random id>/<domain>/<path>/<flash filename>.swf/<object name>.sol

-taken from wiki

For example, I have a swf  at http://example.com/games/uploads/supergame.swf, and when it creates a shared object (SharedObject.getLocal("supergameData");), the SO can be found at #SharedObjects/<random code>/example.com/games/uploads/supergame.swf/supergameData.sol.

While it works well and fine without the localPath parameter, there are certain sites/APIs/services that change the game’s file name by using their automated uploads, feeds, etc as the file name is used in the path. When the developer tries to upload a bug fixed build (v1.0.1), the swf might have another file name hence a problem appears where the previous build’s (v1.0.0) shared object won’t be accessible from the new build due to security reasons.

Although your shared object would be secured against any another swf so it can’t read it, by setting a localPath parameter like “/games” or simply “/”, the shared object can now be read by another swf file within the same domain. Using “/games” would make the SO accessible for any swf within the game directory, while having “/” would make it accessible from any swf within the domain.

Again from the same example but using SharedObject.getLocal("supergameData","/");, makes the SO at #SharedObjects/<random code>/example.com/supergameData.sol. This would make it not dependant on the swf’s file name.

Note: If you set a localPath in which the path doesn’t physically exists as a (sub) directory of the domain the shared object won’t be stored. Luckily with AS3 you’ll be prompted with an Error #2134 when the SharedObject can’t be created, but for AS2, you have to be well aware of this.

Taking advantage of unique names for your shared object name

This is one is something that I have just learned through experimentation and will soon incorporate on my next projects. While setting the localPath parameter to “/” makes the SO accessible to other swfs, there is also a risk that your SO name might be the same with another swf. We wouldn’t want another swf to mess up or overwrite our SO file just because it both uses general and/or generic SO names like “saveData” or “gameData“.

The ultimate tip: Since the SO names allow certain special characters like / (slash), we take advantage of that! Together with the localPath “/”, what I recommend is do a standard setup for your SO names something like:

<company/developer name>/<game name>/<data name>

var mySo:SharedObject = SharedObject.getLocal( "jaycsantos/neolithic/preferences", "/" );
// -- and/or something else like
var mySo:SharedObject = SharedObject.getLocal( "jaycsantos/neolithic/gameData1", "/" );
// --

…will store your SO at something like: #SharedObjects/<random code>/<domain>/#jaycsantos/neolithic/gameData.sol

Although I still have to confirm this with Mac OS and Linux machines. Drop me a line if you find it working with those.

Now ain’t that a little more organized than having all SO on the “/” of the domain!

Prompt and request for shared object size limit increase when your game needs it

There are cases when your shared object has a lot of data in it and it could exceed the default 100kb limit of a user. If this happens, it may cause your shared objects to be written but not read. I have read quite a few times where issues of reading/writing of share objects were resolved by prompting a request to increase local storage limit. This is where the flush() method takes it stand.

Immediately writes a locally persistent shared object to a local file.
AS3
flush(minDiskSpace:int = 0):String

minDiskSpace:int (default = 0) — The minimum disk space, in bytes, that must be allotted for this object.

AS2
flush([minDiskSpace:Number]):Object

minDiskSpace:Number [optional] – An integer specifying the number of bytes that must be allotted for this object. The default value is 0.

With AS3, the flush() method basically does the same thing as with AS2 including their parameters, the only difference made was their return values. AS3 returns a string constant but AS2 returns an object; still their purpose is the same, only the data types have changed.

var mySo:SharedObject = SharedObject.getLocal( 'mySaveName', localPath, secure  );
mySo.data.thingtoSave = myVariable; // your variables
/* stores data into disk and require 10kb of min space
 * if the allocated disk space for local storage is
 * less than 10bk which most probaly be 1kb, then it
 * would prompt a dialog box requesting for an increase
 */
var fushResult:Object = mySo.flush(10000);
trace( fushResult );

So saying simply, if you know your game’s shared object will be greater than a few kbs, you should consider using flush(minDiskSpace) with as your expect maximum size for your data. Why maximum? – think of it as your allowance. Now don’t even consider 2mb or more as an allowance if it’ll never even reach it, play your game at it’s fullest and see what is the size of the shared object using the getSize() method (as2) and the property size (as3) then add around 5-10% of it’s size for an allowance.

Conclusion

After all I have read about using SharedObject is as simple as it could be, in reality it can be a whole lot more than spinning circles for all of what you would need. Well yes, storing a string and recovering it is a piece of icing but storing a complete game state/progress is a new kind of cake to bake. Basically what I have written here are tips and suggestions that I have experienced and with what I have experimented. Either it be accurate or I know not, using SharedObjects has its own work around and is not as simple as most people have said like building a chair, while yes it is not the most complicated but it could be a big question mark on the head for someone new or not familiar to its purpose. I might even consider making a SaveManager or the like but that would be when I get to it. Well, that’s it, this one is quite long but I know it’ll help!

Other Keywords

• Working with Flash Actionscript Shared objects.
• Issues and techniques with Flash Actionscript shared objects.
• Saving data with action script using shared objects.
• Actionscript tips and tricks, shared objects.
• Shared object help, actionscript 2 & actionscript 3.
• Flash actionscript saving & loading locally.
• Flash Actionscript proper way of use when Shared Object does not work.

Where are my display objects?

Before, the Stage class in AS2 is treated as a class whose properties are all static, but with AS3 the new and better Stage class is now a display object. Both making the stage class the main drawing area and where flash content is shown. Basically, just think of it as a practical stage, all actors and props are all objects on display and those who are backstage are objects which are simply not included in the stage yet.

The Stage is a singleton class whereas there can only be one instance of it (imagine watching a play where there are 2 or more stages, its just impossible). Even if you add multiple instances of display objects to the display list, the stage property of each display object still refers to the same Stage object (that goes for loaded SWF files too).

Did you know that the stage is not globally accessible – you can’t call it or reference it from anywhere (unless manually referenced in a variable of course). The simplest way to do so is to use the stage property from any of your display objects which were added to the display list.

Yes, you heard it right from “any” display object, but take note, only if it is already added to the display list. It doesn’t matter if your display object is a child of another display object or how far the display heirarchy it is, as long as it is included in the display list.

Don’t confuse yourself with “Stage” (with capital “S”) and “stage” (with small caps). “Stage” refers to the class flash.display.Stage and “stage” is it’s instance.

Just remember, from a common coding convention: classes begin with capital letters and variables don’t.

If the display object is removed or not yet added from the display list the stage property is just set to null.

Example:

Create a Square.as. The doStuff function just tries to see if the stage is available or not from its own scope.

package
{
    import flash.display.Sprite;
    import flash.display.Graphics;
 
    public class Square extends Sprite
    {
        public function Square()
        {
            // just some drawing
            graphics.lineStyle( 2, 0x666666 );
            graphics.drawCircle( 0, 0, 48 );
            x = 100;
            y = 100;
        }
        public function doStuff()
        {
            if( stage != null ) // if stage is available
            {
                trace( 'I see the stage! '+ stage );
            }
            else // stage is not available
            {
                trace( 'I am not on stage... :( ' );
            }
        }
    }
}

Now create MyStage.as and a new Flash File (actioscript 3.0) then set MyStage as your Document class (just on your properties panel).

package
{
    import flash.display.MovieClip;
 
    public class MyStage extends MovieClip
    {
 
        public function MyStage(){
 
            var square:Square = new Square(); // instanciate a Square
            square.doStuff();
 
            addChild( square ); // add the square instance into display list
            square.doStuff();
        }
 
    }
}

When you test your movie the output panel should display something like:

I am not on stage... :(
I see the stage! [object Stage]

Neat Trick: code snippet

So based on this you can have a neat little trick to determine if your display objects are on stage and added to the display list.

        public function isDisplayed():Boolean
        {
            return Boolean( stage != null );
        }

I hope you understand a little bit more with using display objects and the stage from what I have shared.

Other Keywords

• Working with Actionscript 3 Stage.
• Knowing Flash Actionscript 3 Stage.
• Stage & stage difference in actionscript 3.
• Proper use of Flash Actionscript 3 Stage.

Since flash player 9, site owners were allowed to take use of the additional security. You can control a SWF file’s access to network functionality by setting the allowNetworking parameter in the <object> and <embed> tags in the HTML page that contains the SWF content. It can be included by having:

<object width="100" height="100" data="sample.swf" type="application/x-shockwave-flash">
	<param name="id" value="sampleswf" />
	<param name="allowNetworking" value="internal" />
	<param name="src" value="sample.swf" />
	<param name="name" value="sampleswf" />
</object>

See your help file about this or view the livedocs (as2 or as3) discussing this added security. Basically if this ever happens to a flash game, the developer and/or sponsor are neglected of having click backs to their own sites/portals, which is not a good thing. So I made a little research and test if actionscript can determine if allowNetworking was enabled or not. This test will try to determine if external links are allowed, not exactly return the value of the allowNetworking parameter. I made a sample page here having 2 swfs (as2 & as3) embedded in different ways: using the basic embed-object tags, AC_RunActiveContent.js and swfobject class. As said in that page, the swfs on the left uses allowNetworking set to “internal” so it should say “External links disabled” and the swfs on the right doesn’t so it should say “External links ok”. Then try clicking on the links on each swf and determine if the message displayed respectively complies (either disabled or OK), if so then it pass if not then a fail. And these are the results I had (all with winXP):

In conclusion: I wasn’t successful with AS2, and to mention that the AS2 code that I used is just a trick and not legally proven in anyway. Also if you try to make a trap-like-function with your game/project/swf you should also be aware that opening external links are disabled with standalone flash players by default (which I think implements allowNetworking = “internal” with the standalone player’s sandbox). So the when the AS3 sample is ran using the standalone player you can catch the error number which will be error #0. Note: If you are using another browser which I haven’t tested or another OS, you are very much encouraged to comment out if my sample page worked properly or not with what you have.

Please read the DISCLAIMER first before you do anything with what you’ll see and learn.

Actionscript 2:

import flash.external.ExternalInterface;
 
var allowNetworking;
var str:String;
 
try{
	allowNetworking = ExternalInterface.call(null);
	str = allowNetworking +'';
	if ( str == 'null' ) {
		throw new Error("Error");
	}else{
		_root.test.htmlText = 'external links OKn"'+ str +'"';
	}
}catch( $e ){
	_root.test.htmlText = 'external links DISABLEDn "'+ str +'"';
}
 
btn.onRelease = function(){
	getURL("http://jaycsantos.com","_blank");
}

In AS2, if the ExternalInterface.call() failed it doesn’t throw an error unlike in AS3 so I have to make some workarounds with AS2 to get a return value from any possible function call and ExternalInterface.call() is my only chance. ExternalInterface.call(null) was expected to return a null value when allowNetworking is set to either “internal” or “none” and was supposed to be undefined when not. It was almost a passing code trick but IE has failed once again making the whole AS2 test a failure.

Actionscript 3:

import flash.external.ExternalInterface;
 
var allowNetworking:Object;
 
try{
	allowNetworking = ExternalInterface.call(null);
	test.htmlText = 'external links OK';
}catch( $e:* ){
	test.htmlText = 'external links DISABLEDn err #'+ $e.errorID +'';
}
 
function mouseClickHandler(event:MouseEvent):void {
    navigateToURL(new URLRequest("http://jaycsantos.com/"));
}
btn.addEventListener(MouseEvent.CLICK, mouseClickHandler);

Practically I used ExternalInterface.call(null) instead of trying to instantiate URLRequest because if it succeeds it would open up an external link and might just be blocked by a popup-blocker since the code is ran without user interaction. Unlike AS2, it will simply throw in an error when the network method is restricted.

Please read the DISCLAIMER first before you do anything with what you’ve seen and learned.

I would not recommend using any of this in a professional project or until further tests are made. But it somehow shows logic that it should work especially with the AS3 code, so use at your own risk.