oolite/src/Core/OOShipRegistry.m

/*

OOShipRegistry.m


Copyright (C) 2008-2013 Jens Ayton and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

*/

#import "OOShipRegistry.h"
#import "OOCacheManager.h"
#import "ResourceManager.h"
#import "OOCollectionExtractors.h"
#import "NSDictionaryOOExtensions.h"
#import "OOProbabilitySet.h"
#import "OORoleSet.h"
#import "OOStringParsing.h"
#import "OOMesh.h"
#import "GameController.h"
#import "OOLegacyScriptWhitelist.h"
#import "OODeepCopy.h"
#import "OOColor.h"
#import "OOStringExpander.h"
#import "OOShipLibraryDescriptions.h"
#import "Universe.h"
#import "OOJSScript.h"

#import "OODebugStandards.h"

#define PRELOAD 0


static void DumpStringAddrs(NSDictionary *dict, NSString *context);
static NSComparisonResult SortDemoShipsByName (id a, id b, void* context);
static NSComparisonResult SortDemoCategoriesByName (id a, id b, void* context);


static OOShipRegistry	*sSingleton = nil;


static NSString * const	kShipRegistryCacheName = @"ship registry";
static NSString * const	kShipDataCacheKey = @"ship data";
static NSString * const	kPlayerShipsCacheKey = @"player ships";
static NSString * const	kRoleWeightsCacheKey = @"role weights";
static NSString * const	kDefaultDemoShip = @"coriolis-station";
static NSString * const	kVisualEffectRegistryCacheName = @"visual effect registry";
static NSString * const	kVisualEffectDataCacheKey = @"visual effect data";


@interface OOShipRegistry (OODataLoader)

- (void) loadShipData;
- (void) loadDemoShipConditions;
- (void) loadDemoShips;
- (void) loadCachedRoleProbabilitySets;
- (void) buildRoleProbabilitySets;

- (BOOL) applyLikeShips:(NSMutableDictionary *)ioData withKey:(NSString *)likeKey;
- (BOOL) loadAndMergeShipyard:(NSMutableDictionary *)ioData;
- (BOOL) stripPrivateKeys:(NSMutableDictionary *)ioData;
- (BOOL) makeShipEntriesMutable:(NSMutableDictionary *)ioData;
- (BOOL) loadAndApplyShipDataOverrides:(NSMutableDictionary *)ioData;
- (BOOL) canonicalizeAndTagSubentities:(NSMutableDictionary *)ioData;
- (BOOL) removeUnusableEntries:(NSMutableDictionary *)ioData shipMode:(BOOL)shipMode;
- (BOOL) sanitizeConditions:(NSMutableDictionary *)ioData;

#if PRELOAD
- (BOOL) preloadShipMeshes:(NSMutableDictionary *)ioData;
#endif

- (NSMutableDictionary *) mergeShip:(NSDictionary *)child withParent:(NSDictionary *)parent;
- (void) mergeShipRoles:(NSString *)roles forShipKey:(NSString *)shipKey intoProbabilityMap:(NSMutableDictionary *)probabilitySets;

- (NSDictionary *) canonicalizeSubentityDeclaration:(id)declaration
											forShip:(NSString *)shipKey
										   shipData:(NSDictionary *)shipData
										 fatalError:(BOOL *)outFatalError;
- (NSDictionary *) translateOldStyleSubentityDeclaration:(NSString *)declaration
												 forShip:(NSString *)shipKey
												shipData:(NSDictionary *)shipData
											  fatalError:(BOOL *)outFatalError;
- (NSDictionary *) translateOldStyleFlasherDeclaration:(NSArray *)tokens
											   forShip:(NSString *)shipKey
											fatalError:(BOOL *)outFatalError;
- (NSDictionary *) translateOldStandardBasicSubentityDeclaration:(NSArray *)tokens
														 forShip:(NSString *)shipKey
														shipData:(NSDictionary *)shipData
													  fatalError:(BOOL *)outFatalError;
- (NSDictionary *) validateNewStyleSubentityDeclaration:(NSDictionary *)declaration
												forShip:(NSString *)shipKey
											 fatalError:(BOOL *)outFatalError;
- (NSDictionary *) validateNewStyleFlasherDeclaration:(NSDictionary *)declaration
											  forShip:(NSString *)shipKey
										   fatalError:(BOOL *)outFatalError;
- (NSDictionary *) validateNewStyleStandardSubentityDeclaration:(NSDictionary *)declaration
														forShip:(NSString *)shipKey
													 fatalError:(BOOL *)outFatalError;

- (BOOL) shipIsBallTurretForKey:(NSString *)shipKey inShipData:(NSDictionary *)shipData;

@end


@implementation OOShipRegistry

+ (OOShipRegistry *) sharedRegistry
{
	if (sSingleton == nil)
	{
		sSingleton = [[self alloc] init];
	}
	
	return sSingleton;
}


+ (void) reload
{
	if (sSingleton != nil)
	{
		/* CIM: 'release' doesn't work - the class definition
		 * overrides it, so this leaks memory. Needs a proper reset
		 * method for reloading the ship registry data instead */
		[sSingleton release];
		sSingleton = nil;
		
		(void) [self sharedRegistry];
	}
}


- (id) init
{
	if ((self = [super init]))
	{
		NSAutoreleasePool		*pool = [[NSAutoreleasePool alloc] init];
		OOCacheManager			*cache = [OOCacheManager sharedCache];
		
		_shipData = [[cache objectForKey:kShipDataCacheKey inCache:kShipRegistryCacheName] retain];
		_playerShips = [[cache objectForKey:kPlayerShipsCacheKey inCache:kShipRegistryCacheName] retain];
		_effectData = [[cache objectForKey:kVisualEffectDataCacheKey inCache:kVisualEffectRegistryCacheName] retain];
		if ([_shipData count] == 0)	// Don't accept nil or empty
		{
			[self loadShipData];
			if ([_shipData count] == 0)
			{
				[NSException raise:@"OOShipRegistryLoadFailure" format:@"Could not load any ship data."];
			}
			if ([_playerShips count] == 0)
			{
				[NSException raise:@"OOShipRegistryLoadFailure" format:@"Could not load any player ships."];
			}
		}
		
		[self loadDemoShipConditions];
		[self loadDemoShips]; // testing only
		if ([_demoShips count] == 0)
		{
			[NSException raise:@"OOShipRegistryLoadFailure" format:@"Could not load or synthesize any demo ships."];
		}
		
		[self loadCachedRoleProbabilitySets];
		if (_probabilitySets == nil)
		{
			[self buildRoleProbabilitySets];
			if ([_probabilitySets count] == 0)
			{
				[NSException raise:@"OOShipRegistryLoadFailure" format:@"Could not load or synthesize role probability sets."];
			}
		}
		
		[pool release];
	}
	return self;
}


- (void) dealloc
{
	[_shipData release];
	[_demoShips release];
	[_playerShips release];
	[_probabilitySets release];
	
	[super dealloc];
}


- (NSDictionary *) shipInfoForKey:(NSString *)key
{
	return [_shipData objectForKey:key];
}


- (void) setShipInfoForKey:(NSString *)key with:(NSDictionary *)newShipData
{
	NSMutableDictionary *mutableDict = [NSMutableDictionary dictionaryWithDictionary:_shipData];
	[mutableDict setObject:OODeepCopy(newShipData) forKey:key];
	DESTROY(_shipData);
	_shipData = [[NSDictionary dictionaryWithDictionary:mutableDict] retain];
}


- (NSDictionary *) effectInfoForKey:(NSString *)key
{
	return [_effectData objectForKey:key];
}


- (NSDictionary *) shipyardInfoForKey:(NSString *)key
{
	return [[self shipInfoForKey:key] objectForKey:@"_oo_shipyard"];
}


- (OOProbabilitySet *) probabilitySetForRole:(NSString *)role
{
	if (role == nil)  return nil;
	return [_probabilitySets objectForKey:role];
}


- (NSArray *) demoShipKeys
{
	// with condition scripts in use, can't cache this value
	[self loadDemoShips];

	return [[_demoShips copy] autorelease]; 
}


- (NSArray *) playerShipKeys
{
	return _playerShips;
}

@end


@implementation OOShipRegistry (OOConveniences)

- (NSArray *) shipKeys
{
	return [_shipData allKeys];
}

- (NSArray *) shipRoles
{
	return [_probabilitySets allKeys];
}

- (NSArray *) shipKeysWithRole:(NSString *)role
{
	return [[self probabilitySetForRole:role] allObjects];
}


- (NSString *) randomShipKeyForRole:(NSString *)role
{
	return [[self probabilitySetForRole:role] randomObject];
}

@end


@implementation OOShipRegistry (OODataLoader)

/*	-loadShipData
	
	Load the data for all ships. This consists of five stages:
		* Load merges shipdata.plist dictionary.
		* Apply all like_ship entries.
		* Load shipdata-overrides.plist and apply patches.
		* Load shipyard.plist, add shipyard data into ship dictionaries, and
		  create _playerShips array.
		* Build role->ship type probability sets.
*/
- (void) loadShipData
{
	NSMutableDictionary		*result = nil;
	
	[_shipData release];
	_shipData = nil;
	[_playerShips release];
	_playerShips = nil;
	
	// Load shipdata.plist.
	result = [[[ResourceManager dictionaryFromFilesNamed:@"shipdata.plist"
												inFolder:@"Config"
											   mergeMode:MERGE_BASIC
												   cache:NO] mutableCopy] autorelease];
	if (result == nil)  return;
	
	DumpStringAddrs(result, @"shipdata.plist");
	
	// Make each entry mutable to simplify later stages. Also removes any entries that aren't dictionaries.
	if (![self makeShipEntriesMutable:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished initial cleanup...");
	
	// Apply patches.
	if (![self loadAndApplyShipDataOverrides:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished applying patches...");
	
	// Strip private keys (anything starting with _oo_).
	if (![self stripPrivateKeys:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished stripping private keys...");
	
	// Resolve like_ship entries.
	if (![self applyLikeShips:result withKey:@"like_ship"])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished resolving like_ships...");
	
	// Clean up subentity declarations and tag subentities so they won't be pruned.
	if (![self canonicalizeAndTagSubentities:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished cleaning up subentities...");
	
	// Clean out templates and invalid entries.
	if (![self removeUnusableEntries:result shipMode:YES])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished removing invalid entries...");
	
	// Add shipyard entries into shipdata entries.
	if (![self loadAndMergeShipyard:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished adding shipyard entries...");
	
	// Sanitize conditions.
	if (![self sanitizeConditions:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished validating data...");
	
#if PRELOAD
	// Preload and cache meshes.
	if (![self preloadShipMeshes:result])  return;
	OOLog(@"shipData.load.progress", @"%@", @"Finished loading meshes...");
#endif
	
	_shipData = OODeepCopy(result);
	[[OOCacheManager sharedCache] setObject:_shipData forKey:kShipDataCacheKey inCache:kShipRegistryCacheName];
	
	OOLog(@"shipData.load.done", @"%@", @"Ship data loaded.");

	[_effectData release];
	_effectData = nil;

	result = [[[ResourceManager dictionaryFromFilesNamed:@"effectdata.plist"
												inFolder:@"Config"
											   mergeMode:MERGE_BASIC
												   cache:NO] mutableCopy] autorelease];
	if (result == nil)  return;

	// Make each entry mutable to simplify later stages. Also removes any entries that aren't dictionaries.
	if (![self makeShipEntriesMutable:result])  return;
	OOLog(@"effectData.load.progress", @"%@", @"Finished initial cleanup...");

	// Strip private keys (anything starting with _oo_).
	if (![self stripPrivateKeys:result])  return;
	OOLog(@"effectData.load.progress", @"%@", @"Finished stripping private keys...");
	
	// Resolve like_effect entries.
	if (![self applyLikeShips:result withKey:@"like_effect"])  return;
	OOLog(@"effectData.load.progress", @"%@", @"Finished resolving like_effects...");
	
	// Clean up subentity declarations and tag subentities so they won't be pruned.
	if (![self canonicalizeAndTagSubentities:result])  return;
	OOLog(@"effectData.load.progress", @"%@", @"Finished cleaning up subentities...");
	
	// Clean out templates and invalid entries.
	if (![self removeUnusableEntries:result shipMode:NO])  return;
	OOLog(@"effectData.load.progress", @"%@", @"Finished removing invalid entries...");
	
	_effectData = OODeepCopy(result);
	[[OOCacheManager sharedCache] setObject:_effectData forKey:kVisualEffectDataCacheKey inCache:kVisualEffectRegistryCacheName];
	
	OOLog(@"effectData.load.done", @"%@", @"Effect data loaded.");
}


- (void) loadDemoShipConditions
{
	NSMutableArray *conditionScripts = [[NSMutableArray alloc] init];
	NSEnumerator			*enumerator = nil;
	NSDictionary			*key = nil;
	NSArray					*initialDemoShips = nil;

	initialDemoShips = [ResourceManager arrayFromFilesNamed:@"shiplibrary.plist"
												   inFolder:@"Config"
												   andMerge:YES
													  cache:NO];

	for (enumerator = [initialDemoShips objectEnumerator]; (key = [enumerator nextObject]); )
	{
		NSString *conditions = [key oo_stringForKey:kOODemoShipConditions defaultValue:nil];
		if (conditions != nil)
		{
			[conditionScripts addObject:conditions];
		}
	}

	[[OOCacheManager sharedCache] setObject:conditionScripts forKey:@"demoship conditions" inCache:@"condition scripts"];
	[conditionScripts release];
}


/*	-loadDemoShips
	
	Load demoships.plist, and filter out non-existent ships. If no existing
	ships remain, try adding coriolis; if this fails, add any ship in
	shipdata.
*/
- (void) loadDemoShips
{
	NSEnumerator			*enumerator = nil;
	NSDictionary			*key = nil;
	NSArray					*initialDemoShips = nil;
	NSMutableArray			*demoShips = nil;
	
	DESTROY(_demoShips);
	
	initialDemoShips = [ResourceManager arrayFromFilesNamed:@"shiplibrary.plist"
												   inFolder:@"Config"
												   andMerge:YES
													  cache:NO];
	demoShips = [NSMutableArray arrayWithArray:initialDemoShips];
	
	// Note: iterate over initialDemoShips to avoid mutating the collection being enu,erated.
	for (enumerator = [initialDemoShips objectEnumerator]; (key = [enumerator nextObject]); )
	{
		NSString *shipKey = [key oo_stringForKey:kOODemoShipKey];
		if (![key isKindOfClass:[NSDictionary class]] || [self shipInfoForKey:shipKey] == nil)
		{
			[demoShips removeObject:key];
		}
		else 
		{
			NSString *conditions = [key oo_stringForKey:kOODemoShipConditions defaultValue:nil];
			if (conditions != nil)
			{
				if ([PLAYER status] == STATUS_START_GAME)
				{
					// conditions always false here
					[demoShips removeObject:key];
				}
				else
				{
					OOJSScript *condScript = [UNIVERSE getConditionScript:conditions];
					if (condScript != nil) // should always be non-nil, but just in case
					{
						JSContext			*context = OOJSAcquireContext();
						BOOL OK;
						JSBool allow_use;
						jsval result;
						jsval args[] = { OOJSValueFromNativeObject(context, shipKey) };
						
						OK = [condScript callMethod:OOJSID("allowShowLibraryShip")
										  inContext:context
									  withArguments:args count:sizeof args / sizeof *args
											 result:&result];

						if (OK) OK = JS_ValueToBoolean(context, result, &allow_use);
			
						OOJSRelinquishContext(context);
						if (OK && !allow_use)
						{
							/* if the script exists, the function exists, the function
							 * returns a bool, and that bool is false, hide the
							 * ship. Otherwise allow it as default */
							[demoShips removeObject:key];
						}
					}
				}
			}
		}
	}
	
	if ([demoShips count] == 0)
	{
		NSString *shipKey = nil;
		if ([self shipInfoForKey:kDefaultDemoShip] != nil) 
		{
			shipKey = kDefaultDemoShip;
		}
		else
		{
			shipKey = [[_shipData allKeys] objectAtIndex:0];
		}
		[demoShips addObject:[NSDictionary dictionaryWithObject:shipKey forKey:kOODemoShipKey]];
	}
	
	// now separate out the demoships by class, and add some extra keys
	NSMutableDictionary *demoList = [NSMutableDictionary dictionaryWithCapacity:8];
	NSMutableArray *demoClass = nil;
	foreach(key, demoShips)
	{
		NSString *class = [key oo_stringForKey:kOODemoShipClass defaultValue:@"ship"];
		if ([OOShipLibraryCategoryPlural(class) length] == 0)
		{
			OOLog(@"shipdata.load.warning",@"Unexpected class '%@' in shiplibrary.plist for '%@'",class,[key oo_stringForKey:kOODemoShipKey]);
			class = @"ship";
		}
		demoClass = [demoList objectForKey:class];
		if (demoClass == nil)
		{
			[demoList setObject:[NSMutableArray array] forKey:class];
			demoClass = [demoList objectForKey:class];
		}
		NSMutableDictionary *demoEntry = [NSMutableDictionary dictionaryWithDictionary:key];
		// add "name" object to dictionary from ship definition
		[demoEntry setObject:[[self shipInfoForKey:[demoEntry oo_stringForKey:@"ship"]] oo_stringForKey:kOODemoShipName] forKey:kOODemoShipName];
		// set "class" object to standard ship if not otherwise set
		if (![[demoEntry oo_stringForKey:kOODemoShipClass defaultValue:nil] isEqualToString:class])
		{
			[demoEntry setObject:class forKey:kOODemoShipClass];
		}
		[demoClass addObject:demoEntry];
	}
	// sort each ship list by name
	NSString *demoClassName = nil;
	foreach(demoClassName, demoList)
	{
		[[demoList objectForKey:demoClassName] sortUsingFunction:SortDemoShipsByName context:NULL];
	}

	// and then sort the ship list list by class name
	_demoShips = [[[demoList allValues] sortedArrayUsingFunction:SortDemoCategoriesByName context:NULL] retain];
}


- (void) loadCachedRoleProbabilitySets
{
	NSDictionary			*cachedSets = nil;
	NSMutableDictionary		*restoredSets = nil;
	NSEnumerator			*roleEnum = nil;
	NSString				*role = nil;
	
	cachedSets = [[OOCacheManager sharedCache] objectForKey:kRoleWeightsCacheKey inCache:kShipRegistryCacheName];
	if (cachedSets == nil)  return;
	
	restoredSets = [NSMutableDictionary dictionaryWithCapacity:[cachedSets count]];
	for (roleEnum = [cachedSets keyEnumerator]; (role = [roleEnum nextObject]); )
	{
		[restoredSets setObject:[OOProbabilitySet probabilitySetWithPropertyListRepresentation:[cachedSets objectForKey:role]] forKey:role];
	}
	
	_probabilitySets = [restoredSets copy];
}


- (void) buildRoleProbabilitySets
{
	NSMutableDictionary		*probabilitySets = nil;
	NSEnumerator			*shipEnum = nil;
	NSString				*shipKey = nil;
	NSDictionary			*shipEntry = nil;
	NSString				*roles = nil;
	NSEnumerator			*roleEnum = nil;
	NSString				*role = nil;
	OOProbabilitySet		*pset = nil;
	NSMutableDictionary		*cacheEntry = nil;
	
	probabilitySets = [NSMutableDictionary dictionary];
	
	// Build role sets
	for (shipEnum = [_shipData keyEnumerator]; (shipKey = [shipEnum nextObject]); )
	{
		shipEntry = [_shipData objectForKey:shipKey];
		roles = [shipEntry oo_stringForKey:@"roles"];
		[self mergeShipRoles:roles forShipKey:shipKey intoProbabilityMap:probabilitySets];
	}
	
	// Convert role sets to immutable form, and build cache entry.
	// Note: we iterate over a copy of the keys to avoid mutating while iterating.
	cacheEntry = [NSMutableDictionary dictionaryWithCapacity:[probabilitySets count]];
	for (roleEnum = [[probabilitySets allKeys] objectEnumerator]; (role = [roleEnum nextObject]); )
	{
		pset = [probabilitySets objectForKey:role];
		pset = [[pset copy] autorelease];
		[probabilitySets setObject:pset forKey:role];
		[cacheEntry setObject:[pset propertyListRepresentation] forKey:role];
	}
	
	_probabilitySets = [probabilitySets copy];
	[[OOCacheManager sharedCache] setObject:cacheEntry forKey:kRoleWeightsCacheKey inCache:kShipRegistryCacheName];
}


/*	-applyLikeShips:
	
	Implement like_ship by copying inherited ship and overwriting with child
	ship values. Done iteratively to report recursive references of arbitrary
	depth. Also removes and reports ships whose like_ship entry does not
	resolve, and handles reference loops by removing all ships involved.
 
	We start with a set of keys all ships that have a like_ships entry. In
	each iteration, every ship whose like_ship entry does not refer to a ship
	which itself has a like_ship entry is finalized. If the set of pending
	ships does not shrink in an iteration, the remaining ships cannot be
	resolved (either their like_ships do not exist, or they form reference
	cycles) so we stop looping and report it.
*/
- (BOOL) applyLikeShips:(NSMutableDictionary *)ioData withKey:(NSString *)likeKey
{
	NSMutableSet			*remainingLikeShips = nil;
	NSEnumerator			*enumerator = nil;
	NSString				*key = nil;
	NSString				*parentKey = nil;
	NSDictionary			*shipEntry = nil;
	NSDictionary			*parentEntry = nil;
	NSUInteger				count, lastCount;
	NSMutableArray			*reportedBadShips = nil;
	
	// Build set of ships with like_ship references
	remainingLikeShips = [NSMutableSet set];
	for (enumerator = [ioData keyEnumerator]; (key = [enumerator nextObject]); )
	{
		shipEntry = [ioData objectForKey:key];
		if ([shipEntry oo_stringForKey:likeKey] != nil)
		{
			[remainingLikeShips addObject:key];
		}
	}
	
	count = lastCount = [remainingLikeShips count];
	while (count != 0)
	{
		for (enumerator = [[[remainingLikeShips copy] autorelease] objectEnumerator]; (key = [enumerator nextObject]); )
		{
			// Look up like_ship entry
			shipEntry = [ioData objectForKey:key];
			parentKey = [shipEntry objectForKey:likeKey];
			if (![remainingLikeShips containsObject:parentKey])
			{
				// If parent is fully resolved, we can resolve this child.
				parentEntry = [ioData objectForKey:parentKey];
				shipEntry = [self mergeShip:shipEntry withParent:parentEntry];
				if (shipEntry != nil)
				{
					[remainingLikeShips removeObject:key];
					[ioData setObject:shipEntry forKey:key];
				}
			}
		}
		
		count = [remainingLikeShips count];
		if (count == lastCount)
		{
			/*	Fail: we couldn't resolve all like_ship entries.
				Remove unresolved entries, building a list of the ones that
				don't have is_external_dependency set.
			*/
			reportedBadShips = [NSMutableArray array];
			for (enumerator = [remainingLikeShips objectEnumerator]; (key = [enumerator nextObject]); )
			{
				if (![[ioData oo_dictionaryForKey:key] oo_boolForKey:@"is_external_dependency"])
				{
					[reportedBadShips addObject:key];
				}
				[ioData removeObjectForKey:key];
			}
			
			if ([reportedBadShips count] != 0)
			{
				[reportedBadShips sortUsingSelector:@selector(caseInsensitiveCompare:)];
				OOLogERR(@"shipData.merge.failed", @"one or more shipdata.plist entries have %@ references that cannot be resolved: %@", likeKey, [reportedBadShips componentsJoinedByString:@", "]); // FIXME: distinguish shipdata and effectdata
				OOStandardsError(@"Likely missing a dependency in a manifest.plist");
			}
			break;
		}
		lastCount = count;
	}
	
	return YES;
}


- (NSMutableDictionary *) mergeShip:(NSDictionary *)child withParent:(NSDictionary *)parent
{
	NSMutableDictionary *result = [[parent mutableCopy] autorelease];
	if (result == nil)  return nil;
	
	[result addEntriesFromDictionary:child];
	[result removeObjectForKey:@"like_ship"];
	
	// Certain properties cannot be inherited.
	if ([child oo_stringForKey:@"display_name"] == nil)  [result removeObjectForKey:@"display_name"];
	if ([child oo_stringForKey:@"is_template"] == nil)  [result removeObjectForKey:@"is_template"];
	
	// Since both 'scanClass' and 'scan_class' are accepted as valid keys for the scanClass property,
	// we may end up with conflicting scanClass and scan_class keys from like_ship relationships getting
	// merged in the result dictionary. We want to always have the child overriding the parent setting
	// and we do that by determining which of the two keys belongs to the child dictionary and removing
	// the other one from the result - Nikos 20100512
	if ([result oo_stringForKey:@"scan_class"] != nil && [result oo_stringForKey:@"scanClass"] != nil)
	{
		if ([child oo_stringForKey:@"scanClass"] != nil)
			[result removeObjectForKey:@"scan_class"];
		else
			[result removeObjectForKey:@"scanClass"];
	}
	// TODO: all normalised/non-normalised value name pairs need to be catered for. - Kaks 2010-05-13
	if ([result oo_stringForKey:@"escort_role"] != nil && [result oo_stringForKey:@"escort-role"] != nil)
	{
		if ([child oo_stringForKey:@"escort-role"] != nil)
			[result removeObjectForKey:@"escort_role"];
		else
			[result removeObjectForKey:@"escort-role"];
	}
	if ([result oo_stringForKey:@"escort_ship"] != nil && [result oo_stringForKey:@"escort-ship"] != nil)
	{
		if ([child oo_stringForKey:@"escort-ship"] != nil)
			[result removeObjectForKey:@"escort_ship"];
		else
			[result removeObjectForKey:@"escort-ship"];
	}
	if ([result oo_stringForKey:@"is_carrier"] != nil && [result oo_stringForKey:@"isCarrier"] != nil)
	{
		if ([child oo_stringForKey:@"isCarrier"] != nil)
			[result removeObjectForKey:@"is_carrier"];
		else
			[result removeObjectForKey:@"isCarrier"];
	}
	if ([result oo_stringForKey:@"has_shipyard"] != nil && [result oo_stringForKey:@"hasShipyard"] != nil)
	{
		if ([child oo_stringForKey:@"hasShipyard"] != nil)
			[result removeObjectForKey:@"has_shipyard"];
		else
			[result removeObjectForKey:@"hasShipyard"];
	}	
	return result;
}


- (BOOL) makeShipEntriesMutable:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSDictionary			*shipEntry = nil;
	
	for (shipKeyEnum = [[ioData allKeys] objectEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		if (![shipEntry isKindOfClass:[NSDictionary class]])
		{
			OOLogERR(@"shipData.load.badEntry", @"the shipdata.plist entry \"%@\" is not a dictionary.", shipKey);
			[ioData removeObjectForKey:shipKey];
		}
		else
		{
			shipEntry = [shipEntry mutableCopy];
			
			[ioData setObject:shipEntry forKey:shipKey];
			[shipEntry release];
		}
	}
	
	return YES;
}


- (BOOL) loadAndApplyShipDataOverrides:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	NSDictionary			*overrides = nil;
	NSDictionary			*overridesEntry = nil;
	
	overrides = [ResourceManager dictionaryFromFilesNamed:@"shipdata-overrides.plist"
												 inFolder:@"Config"
												mergeMode:MERGE_SMART
													cache:NO];
	
	for (shipKeyEnum = [overrides keyEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		if (shipEntry != nil)
		{
			overridesEntry = [overrides objectForKey:shipKey];
			if (![overridesEntry isKindOfClass:[NSDictionary class]])
			{
				OOLogERR(@"shipData.load.error", @"the shipdata-overrides.plist entry \"%@\" is not a dictionary.", shipKey);
			}
			else
			{
				[shipEntry addEntriesFromDictionary:overridesEntry];
			}
		}
	}
	
	return YES;
}


- (BOOL) stripPrivateKeys:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	NSEnumerator			*attrKeyEnum = nil;
	NSString				*attrKey = nil;
	
	for (shipKeyEnum = [ioData keyEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		
		for (attrKeyEnum = [shipEntry keyEnumerator]; (attrKey = [attrKeyEnum nextObject]); )
		{
			if ([attrKey hasPrefix:@"_oo_"])
			{
				[shipEntry removeObjectForKey:attrKey];
			}
		}
	}
	
	return YES;
}


/*	-loadAndMergeShipyard:
	
	Load shipyard.plist, add its entries to appropriate shipyard entries as
	a dictionary under the key "shipyard", and build list of player ships.
	Before that, we strip out any "shipyard" entries already in shipdata, and
	apply any shipyard-overrides.plist stuff to shipyard.
*/
- (BOOL) loadAndMergeShipyard:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	NSDictionary			*shipyard = nil;
	NSDictionary			*shipyardOverrides = nil;
	NSDictionary			*shipyardEntry = nil;
	NSDictionary			*shipyardOverridesEntry = nil;
	NSMutableArray			*playerShips = nil;
	
	// Strip out any shipyard stuff in shipdata (there shouldn't be any).
	for (shipKeyEnum = [ioData keyEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		if ([shipEntry objectForKey:@"_oo_shipyard"] != nil)
		{
			[shipEntry removeObjectForKey:@"_oo_shipyard"];
		}
	}
	
	shipyard = [ResourceManager dictionaryFromFilesNamed:@"shipyard.plist"
												inFolder:@"Config"
											   mergeMode:MERGE_BASIC
												   cache:NO];
	shipyardOverrides = [ResourceManager dictionaryFromFilesNamed:@"shipyard-overrides.plist"
														 inFolder:@"Config"
														mergeMode:MERGE_SMART
															cache:NO];
	
	playerShips = [NSMutableArray arrayWithCapacity:[shipyard count]];
	
	// Insert merged shipyard and shipyardOverrides entries.
	for (shipKeyEnum = [shipyard keyEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		if (shipEntry != nil)
		{
			shipyardEntry = [shipyard objectForKey:shipKey];
			shipyardOverridesEntry = [shipyardOverrides objectForKey:shipKey];
			shipyardEntry = [shipyardEntry dictionaryByAddingEntriesFromDictionary:shipyardOverridesEntry];
			
			[shipEntry setObject:shipyardEntry forKey:@"_oo_shipyard"];
			
			[playerShips addObject:shipKey];
		}
		else
		{
			OOLogWARN(@"shipData.load.shipyard.unknown", @"the shipyard.plist entry \"%@\" does not have a corresponding shipdata.plist entry, ignoring.", shipKey);
		}
	}
	
	_playerShips = [playerShips copy];
	[[OOCacheManager sharedCache] setObject:_playerShips forKey:kPlayerShipsCacheKey inCache:kShipRegistryCacheName];
	
	return YES;
}


- (BOOL) canonicalizeAndTagSubentities:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	NSArray					*subentityDeclarations = nil;
	NSEnumerator			*subentityEnum = nil;
	id						subentityDecl = nil;
	NSDictionary			*subentityDict = nil;
	NSString				*subentityKey = nil;
	NSMutableDictionary		*subentityShipEntry = nil;
	NSMutableSet			*badSubentities = nil;
	NSString				*badSubentitiesList = nil;
	NSMutableArray			*okSubentities = nil;
	BOOL					remove, fatal;
	
	// Convert all subentity declarations to dictionaries and add
	// _oo_is_subentity=YES to all entries used as subentities.
	
	// Iterate over all ships. (Iterates over a copy of keys since it mutates the dictionary.)
	for (shipKeyEnum = [[ioData allKeys] objectEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		remove = NO;
		badSubentities = nil;
		
		// Iterate over each subentity declaration of each ship
		subentityDeclarations = [shipEntry oo_arrayForKey:@"subentities"];
		if (subentityDeclarations != nil)
		{
			okSubentities = [NSMutableArray arrayWithCapacity:[subentityDeclarations count]];
			for (subentityEnum = [subentityDeclarations objectEnumerator]; (subentityDecl = [subentityEnum nextObject]); )
			{
				subentityDict = [self canonicalizeSubentityDeclaration:subentityDecl forShip:shipKey shipData:ioData fatalError:&fatal];
				
				// If entry is broken, we need to kill this ship.
				if (fatal)
				{
					OOStandardsError(@"Bad subentity definition found");
					remove = YES;
				}
				else if (subentityDict != nil)
				{
					[okSubentities addObject:subentityDict];
					
					// Tag subentities.
					if (![[subentityDict oo_stringForKey:@"type"] isEqualToString:@"flasher"])
					{
						subentityKey = [subentityDict oo_stringForKey:@"subentity_key"];
						subentityShipEntry = [ioData objectForKey:subentityKey];
						if (subentityKey == nil || subentityShipEntry == nil)
						{
							// Oops, reference to non-existent subent.
							if (badSubentities == nil)  badSubentities = [NSMutableSet set];
							[badSubentities addObject:subentityKey];
						}
						else
						{
							// Subent exists, add _oo_is_subentity so roles aren't required.
							[subentityShipEntry oo_setBool:YES forKey:@"_oo_is_subentity"];
						}
					}
				}
			}
			
			// Set updated subentity list.
			if ([okSubentities count] != 0)
			{
				[shipEntry setObject:okSubentities forKey:@"subentities"];
			}
			else
			{
				[shipEntry removeObjectForKey:@"subentities"];
			}
			
			if (badSubentities != nil)
			{
				if (![shipEntry oo_boolForKey:@"is_external_dependency"])
				{
					badSubentitiesList = [[[badSubentities allObjects] sortedArrayUsingSelector:@selector(caseInsensitiveCompare:)] componentsJoinedByString:@", "];
					OOLogERR(@"shipData.load.error", @"the shipdata.plist entry \"%@\" has unresolved subentit%@ %@.", shipKey, ([badSubentities count] == 1) ? @"y" : @"ies", badSubentitiesList);
					OOStandardsError(@"Bad subentity definition found");
				}
				remove = YES;
			}
			
			if (remove)
			{
				// Removal is deferred to avoid bogus "entry doesn't exist" errors.
				[shipEntry oo_setBool:YES forKey:@"_oo_deferred_remove"];
			}
		}
	}
	
	return YES;
}


- (BOOL) removeUnusableEntries:(NSMutableDictionary *)ioData shipMode:(BOOL)shipMode
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	BOOL					remove;
	NSString				*modelName = nil;
	
	// Clean out invalid entries and templates. (Iterates over a copy of keys since it mutates the dictionary.)
	for (shipKeyEnum = [[ioData allKeys] objectEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		remove = NO;
		
		if ([shipEntry oo_boolForKey:@"is_template"] || [shipEntry oo_boolForKey:@"_oo_deferred_remove"])  remove = YES;
		else if (shipMode && [[shipEntry oo_stringForKey:@"roles"] length] == 0 && ![shipEntry oo_boolForKey:@"_oo_is_subentity"] && ![shipEntry oo_boolForKey:@"_oo_is_effect"])
		{
			OOLogERR(@"shipData.load.error", @"the shipdata.plist entry \"%@\" specifies no %@.", shipKey, @"roles");
			remove = YES;
			OOStandardsError(@"Error in shipdata.plist");
		}
		else
		{
			modelName = [shipEntry oo_stringForKey:@"model"];
			if (shipMode && [modelName length] == 0)
			{
				OOLogERR(@"shipData.load.error", @"the shipdata.plist entry \"%@\" specifies no %@.", shipKey, @"model");
				OOStandardsError(@"Error in shipdata.plist");
				remove = YES;
			}
			else if ([modelName length] != 0 && [ResourceManager pathForFileNamed:modelName inFolder:@"Models"] == nil)
			{
				OOLogERR(@"shipData.load.error", @"the shipdata.plist entry \"%@\" specifies non-existent model \"%@\".", shipKey, modelName);
				OOStandardsError(@"Error in shipdata.plist");
				remove = YES;
			}
		}
		if (remove)  [ioData removeObjectForKey:shipKey];
	}
	
	return YES;
}


/*	Transform conditions, determinant (if conditions array) and
	shipyard.conditions from hasShipyard to sanitized form.
  Also get list of condition_scripts
*/
- (BOOL) sanitizeConditions:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	NSMutableDictionary		*mutableShipyard = nil;
	NSArray					*conditions = nil;
	NSArray					*hasShipyard = nil;
	NSArray					*shipyardConditions = nil;
	NSString        *condition_script = nil;
	NSString        *shipyard_condition_script = nil;
	
	NSMutableArray *conditionScripts = [[NSMutableArray alloc] init];

	for (shipKeyEnum = [[ioData allKeys] objectEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		shipEntry = [ioData objectForKey:shipKey];
		conditions = [shipEntry objectForKey:@"conditions"];
		condition_script = [shipEntry oo_stringForKey:@"condition_script"];
		if (condition_script != nil)
		{
			if (![conditionScripts containsObject:condition_script])
			{
				[conditionScripts addObject:condition_script];
			}
		}

		hasShipyard = [shipEntry objectForKey:@"has_shipyard"];
		if (![hasShipyard isKindOfClass:[NSArray class]])  hasShipyard = nil;	// May also be fuzzy boolean
		if (hasShipyard == nil)
		{
			hasShipyard = [shipEntry objectForKey:@"hasShipyard"];
			if (![hasShipyard isKindOfClass:[NSArray class]])  hasShipyard = nil;	// May also be fuzzy boolean
		}
		shipyardConditions = [[shipEntry oo_dictionaryForKey:@"_oo_shipyard"] objectForKey:@"conditions"];
		shipyard_condition_script = [[shipEntry oo_dictionaryForKey:@"_oo_shipyard"] oo_stringForKey:@"condition_script"];
		if (shipyard_condition_script != nil)
		{
			if (![conditionScripts containsObject:shipyard_condition_script])
			{
				[conditionScripts addObject:shipyard_condition_script];
			}
		}

		
		if (conditions == nil && hasShipyard && shipyardConditions == nil)  continue;
		
		if (conditions != nil)
		{
			OOStandardsDeprecated([NSString stringWithFormat:@"The 'conditions' key is deprecated in shipdata entry %@",shipKey]);
			if (!OOEnforceStandards())
			{
				if ([conditions isKindOfClass:[NSArray class]])
				{
					conditions = OOSanitizeLegacyScriptConditions(conditions, [NSString stringWithFormat:@"<shipdata.plist entry \"%@\">", shipKey]);
				}
				else
				{
					OOLogWARN(@"shipdata.load.warning", @"conditions for shipdata.plist entry \"%@\" are not an array, ignoring.", shipKey);
					conditions = nil;
				}
			
				if (conditions != nil)
				{
					[shipEntry setObject:conditions forKey:@"conditions"];
				}
				else
				{
					[shipEntry removeObjectForKey:@"conditions"];
				}
			}
		}
		
		if (hasShipyard != nil)
		{
			hasShipyard = OOSanitizeLegacyScriptConditions(hasShipyard, [NSString stringWithFormat:@"<shipdata.plist entry \"%@\" hasShipyard conditions>", shipKey]);
			OOStandardsDeprecated([NSString stringWithFormat:@"Use of legacy script conditions in the 'has_shipyard' key is deprecated in shipyard entry %@",shipKey]);
			if (!OOEnforceStandards())
			{
				if (hasShipyard != nil)
				{
					[shipEntry setObject:hasShipyard forKey:@"has_shipyard"];
				}
				else
				{
					[shipEntry removeObjectForKey:@"hasShipyard"];
					[shipEntry removeObjectForKey:@"has_shipyard"];
				}
			}
		}
		
		if (shipyardConditions != nil)
		{
			OOStandardsDeprecated([NSString stringWithFormat:@"The 'conditions' key is deprecated in shipyard entry %@",shipKey]);
			if (!OOEnforceStandards())
			{
				mutableShipyard = [[[shipEntry oo_dictionaryForKey:@"_oo_shipyard"] mutableCopy] autorelease];
			
				if ([shipyardConditions isKindOfClass:[NSArray class]])
				{
					shipyardConditions = OOSanitizeLegacyScriptConditions(shipyardConditions, [NSString stringWithFormat:@"<shipyard.plist entry \"%@\">", shipKey]);
				}
				else
				{
					OOLogWARN(@"shipdata.load.warning", @"conditions for shipyard.plist entry \"%@\" are not an array, ignoring.", shipKey);
					shipyardConditions = nil;
				}
			
				if (shipyardConditions != nil)
				{
					[mutableShipyard setObject:shipyardConditions forKey:@"conditions"];
				}
				else
				{
					[mutableShipyard removeObjectForKey:@"conditions"];
				}
			
				[shipEntry setObject:mutableShipyard forKey:@"_oo_shipyard"];
			}
		}
	}

	[[OOCacheManager sharedCache] setObject:conditionScripts forKey:@"ship conditions" inCache:@"condition scripts"];
	[conditionScripts release];

	return YES;
}


#if PRELOAD
- (BOOL) preloadShipMeshes:(NSMutableDictionary *)ioData
{
	NSEnumerator			*shipKeyEnum = nil;
	NSString				*shipKey = nil;
	NSMutableDictionary		*shipEntry = nil;
	BOOL					remove;
	NSString				*modelName = nil;
	OOMesh					*mesh = nil;
	NSAutoreleasePool		*pool = nil;
	NSUInteger				i = 0, count;
	
	count = [ioData count];
	
	// Preload ship meshes. (Iterates over a copy of keys since it mutates the dictionary.)
	for (shipKeyEnum = [[ioData allKeys] objectEnumerator]; (shipKey = [shipKeyEnum nextObject]); )
	{
		pool = [[NSAutoreleasePool alloc] init];
		
		[[GameController sharedController] setProgressBarValue:(float)i++ / (float)count];
		
		shipEntry = [ioData objectForKey:shipKey];
		remove = NO;
		
		modelName = [shipEntry oo_stringForKey:@"model"];
		mesh = [OOMesh meshWithName:modelName
				 materialDictionary:[shipEntry oo_dictionaryForKey:@"materials"]
				  shadersDictionary:[shipEntry oo_dictionaryForKey:@"shaders"]
							 smooth:[shipEntry oo_boolForKey:@"smooth"]
					   shaderMacros:nil
				shaderBindingTarget:nil];
		
		[pool release];	// NOTE: mesh is now invalid, but pointer nil check is OK.
		
		if (mesh == nil)
		{
			// FIXME: what if it's a subentity? Need to rearrange things.
			OOLogERR(@"shipData.load.error", @"model \"%@\" could not be loaded for ship \"%@\", removing.", modelName, shipKey);
			[ioData removeObjectForKey:shipKey];
		}
	}
	
	[[GameController sharedController] setProgressBarValue:-1.0f];
	
	return YES;
}
#endif


- (void) mergeShipRoles:(NSString *)roles
			 forShipKey:(NSString *)shipKey
	 intoProbabilityMap:(NSMutableDictionary *)probabilitySets
{
	NSDictionary			*rolesAndWeights = nil;
	NSEnumerator			*roleEnum = nil;
	NSString				*role = nil;
	OOMutableProbabilitySet	*probSet = nil;

	
	/*	probabilitySets is a dictionary whose keys are roles and whose values
		are mutable probability sets, whose values are ship keys.
		
		When creating new ships Oolite looks up this probability map.
		To upgrade all soliton 'thargon' roles to 'EQ_THARGON' we need
		to swap these roles here.
	*/
	
	rolesAndWeights = OOParseRolesFromString(roles);
  // add default [shipKey] role
	NSMutableDictionary *mutable = [NSMutableDictionary dictionaryWithDictionary:rolesAndWeights];
	[mutable setObject:[NSNumber numberWithFloat:1.0] forKey:[[[NSString alloc] initWithFormat:@"[%@]",shipKey] autorelease]];
	rolesAndWeights = mutable;
	
	id thargonValue = [rolesAndWeights objectForKey:@"thargon"];
	if (thargonValue != nil && [rolesAndWeights objectForKey:@"EQ_THARGON"] == nil)
	{
		NSMutableDictionary *mutable = [NSMutableDictionary dictionaryWithDictionary:rolesAndWeights];
		[mutable setObject:thargonValue forKey:@"EQ_THARGON"];
		rolesAndWeights = mutable;
	}
	
	for (roleEnum = [rolesAndWeights keyEnumerator]; (role = [roleEnum nextObject]); )
	{
		probSet = [probabilitySets objectForKey:role];
		if (probSet == nil)
		{
			probSet = [OOMutableProbabilitySet probabilitySet];
			[probabilitySets setObject:probSet forKey:role];
		}
		
		[probSet setWeight:[rolesAndWeights oo_floatForKey:role] forObject:shipKey];
	}
}


- (NSDictionary *) canonicalizeSubentityDeclaration:(id)declaration
											forShip:(NSString *)shipKey
										   shipData:(NSDictionary *)shipData
										 fatalError:(BOOL *)outFatalError
{
	NSDictionary			*result = nil;
	
	assert(outFatalError != NULL);
	*outFatalError = NO;
	
	if ([declaration isKindOfClass:[NSString class]])
	{
		// Update old-style string-based declaration.
		OOStandardsDeprecated([NSString stringWithFormat:@"Old style sub-entity declarations are deprecated in %@",shipKey]);
		if (!OOEnforceStandards())
		{
			result = [self translateOldStyleSubentityDeclaration:declaration
														 forShip:shipKey
														shipData:shipData
													  fatalError:outFatalError];
		}
		if (result != nil)
		{
			// Ensure internal translation made sense, and clean up a bit.
			result = [self validateNewStyleSubentityDeclaration:result
														forShip:shipKey
													 fatalError:outFatalError];
		}
	}
	else if ([declaration isKindOfClass:[NSDictionary class]])
	{
		// Validate dictionary-based declaration.
		result = [self validateNewStyleSubentityDeclaration:declaration
													forShip:shipKey
												 fatalError:outFatalError];
	}
	else
	{
		OOLogERR(@"shipData.load.error.badSubentity", @"subentity declaration for ship %@ should be string or dictionary, found %@.", shipKey, [declaration class]);
		*outFatalError = YES;
	}
	
	// For frangible ships, bad subentities are non-fatal.
	if (*outFatalError && [[shipData oo_dictionaryForKey:shipKey] oo_boolForKey:@"frangible"])  *outFatalError = NO;
	
	return result;
}


- (NSDictionary *) translateOldStyleSubentityDeclaration:(NSString *)declaration
												 forShip:(NSString *)shipKey
												shipData:(NSDictionary *)shipData
											  fatalError:(BOOL *)outFatalError
{
	NSArray					*tokens = nil;
	NSString				*subentityKey = nil;
	BOOL					isFlasher;
	
	tokens = ScanTokensFromString(declaration);
	
	subentityKey = [tokens objectAtIndex:0];
	isFlasher = [subentityKey isEqualToString:@"*FLASHER*"];
	
	// Sanity check: require eight tokens.
	if ([tokens count] != 8)
	{
		if (!isFlasher)
		{
			OOLogERR(@"shipData.load.error.badSubentity", @"the shipdata.plist entry \"%@\" has a broken subentity definition \"%@\" (should have 8 tokens, has %lu).", shipKey, subentityKey, [tokens count]);
			*outFatalError = YES;
		}
		else
		{
			OOLogWARN(@"shipData.load.warning.badFlasher", @"the shipdata.plist entry \"%@\" has a broken flasher definition (should have 8 tokens, has %lu). This flasher will be ignored.", shipKey, [tokens count]);
		}
		return nil;
	}
	
	if (isFlasher)
	{
		return [self translateOldStyleFlasherDeclaration:tokens
												 forShip:shipKey
											  fatalError:outFatalError];
	}
	else
	{
		return [self translateOldStandardBasicSubentityDeclaration:tokens
														   forShip:shipKey
														  shipData:shipData
														fatalError:outFatalError];
	}
}


- (NSDictionary *) translateOldStyleFlasherDeclaration:(NSArray *)tokens
											   forShip:(NSString *)shipKey
											fatalError:(BOOL *)outFatalError
{
	Vector					position;
	float					size, frequency, phase, hue;
	NSDictionary			*colorDict = nil;
	NSDictionary			*result = nil;
	
	position.x = [tokens oo_floatAtIndex:1];
	position.y = [tokens oo_floatAtIndex:2];
	position.z = [tokens oo_floatAtIndex:3];
	
	hue = [tokens oo_floatAtIndex:4];
	frequency = [tokens oo_floatAtIndex:5];
	phase = [tokens oo_floatAtIndex:6];
	size = [tokens oo_floatAtIndex:7];
	
	colorDict = [NSDictionary dictionaryWithObject:[NSNumber numberWithFloat:hue] forKey:@"hue"];
	
	result = [NSDictionary dictionaryWithObjectsAndKeys:
			  @"flasher", @"type",
			  OOPropertyListFromVector(position), @"position",
			  [NSArray arrayWithObject:colorDict], @"colors",
			  [NSNumber numberWithFloat:frequency], @"frequency",
			  [NSNumber numberWithFloat:phase], @"phase",
			  [NSNumber numberWithFloat:size], @"size",
			  nil];
	
	OOLog(@"shipData.translateSubentity.flasher", @"Translated flasher declaration \"%@\" to %@", [tokens componentsJoinedByString:@" "], result);
	
	return result;
}


- (NSDictionary *) translateOldStandardBasicSubentityDeclaration:(NSArray *)tokens
														 forShip:(NSString *)shipKey
														shipData:(NSDictionary *)shipData
													  fatalError:(BOOL *)outFatalError
{
	NSString				*subentityKey = nil;
	Vector					position;
	Quaternion				orientation;
	NSMutableDictionary		*result = nil;
	BOOL					isTurret, isDock = NO;
	
	subentityKey = [tokens oo_stringAtIndex:0];
	
	isTurret = [self shipIsBallTurretForKey:subentityKey inShipData:shipData];
	
	position.x = [tokens oo_floatAtIndex:1];
	position.y = [tokens oo_floatAtIndex:2];
	position.z = [tokens oo_floatAtIndex:3];
	
	orientation.w = [tokens oo_floatAtIndex:4];
	orientation.x = [tokens oo_floatAtIndex:5];
	orientation.y = [tokens oo_floatAtIndex:6];
	orientation.z = [tokens oo_floatAtIndex:7];
	
	if(orientation.w == 0 && orientation.x == 0 && orientation.y == 0 && orientation.z == 0) 
	{
		orientation.w = 1; // avoid dividing by zero.
		OOLogWARN(@"shipData.load.error", @"The ship %@ has an undefined orientation for its %@ subentity. Setting it now at (1,0,0,0)", shipKey, subentityKey);
	}
	
	quaternion_normalize(&orientation);
	
	if (!isTurret)
	{
		isDock = [subentityKey rangeOfString:@"dock"].location != NSNotFound;
	}
	
	result = [NSMutableDictionary dictionaryWithCapacity:5];
	[result setObject:isTurret ? @"ball_turret" : @"standard" forKey:@"type"];
	[result setObject:subentityKey forKey:@"subentity_key"];
	[result oo_setVector:position forKey:@"position"];
	[result oo_setQuaternion:orientation forKey:@"orientation"];
	if (isDock)  [result oo_setBool:YES forKey:@"is_dock"];
	
	OOLog(@"shipData.translateSubentity.standard", @"Translated subentity declaration \"%@\" to %@", [tokens componentsJoinedByString:@" "], result);
	
	return [[result copy] autorelease];
}


- (NSDictionary *) validateNewStyleSubentityDeclaration:(NSDictionary *)declaration
												forShip:(NSString *)shipKey
											 fatalError:(BOOL *)outFatalError
{
	NSString				*type = nil;
	
	type = [declaration oo_stringForKey:@"type"];
	if (type == nil)  type = @"standard";
	
	if ([type isEqualToString:@"flasher"])
	{
		return [self validateNewStyleFlasherDeclaration:declaration forShip:shipKey fatalError:outFatalError];
	}
	else if ([type isEqualToString:@"standard"] || [type isEqualToString:@"ball_turret"])
	{
		return [self validateNewStyleStandardSubentityDeclaration:declaration forShip:shipKey fatalError:outFatalError];
	}
	else
	{
		OOLogERR(@"shipData.load.error.badSubentity", @"subentity declaration for ship %@ does not declare a valid type (must be standard, flasher or ball_turret).", shipKey);
		*outFatalError = YES;
		return nil;
	}
}


- (NSDictionary *) validateNewStyleFlasherDeclaration:(NSDictionary *)declaration
											  forShip:(NSString *)shipKey
										   fatalError:(BOOL *)outFatalError
{
	NSMutableDictionary		*result = nil;
	Vector					position = kZeroVector;
	NSArray					*colors = nil;
	id						colorDesc = nil;
	float					size, frequency, phase, brightfraction;
	BOOL					initiallyOn;
	
#define kDefaultFlasherColor @"redColor"
	
	// "Validate" is really "clean up", since all values have defaults.
	colors = [declaration oo_arrayForKey:@"colors"];
	if ([colors count] == 0)
	{
		colorDesc = [declaration objectForKey:@"color"];
		if (colorDesc == nil) colorDesc = kDefaultFlasherColor;
		if ([colorDesc isKindOfClass:[NSArray class]])
		{
			// an easy made error is adding an array to "color" instead of "colors"
			OOLogWARN(@"shipData.load.warning.flasher.badColor", @"changing flasher for ship %@ from a color to a colors definition.", shipKey);
			colors = colorDesc;
		}
		else
		{
			colors = [NSArray arrayWithObject:colorDesc];
		}
	}
	
	// Validate colours.
	NSMutableArray *validColors = [NSMutableArray arrayWithCapacity:[colors count]];
	foreach (colorDesc, colors)
	{
		OOColor *color = [OOColor colorWithDescription:colorDesc];
		if (color != nil)
		{
			[validColors addObject:[color normalizedArray]];
		}
		else
		{
			OOLogWARN(@"shipdata.load.warning.flasher.badColor", @"skipping invalid colour specifier for flasher for ship %@.", shipKey);
		}
	}
	// Ensure there's at least one.
	if ([validColors count] == 0)
	{
		[validColors addObject:kDefaultFlasherColor];
	}
	colors = validColors;
	
	position = [declaration oo_vectorForKey:@"position"];
	
	size = [declaration oo_floatForKey:@"size" defaultValue:8.0];
	
	if (size <= 0)
	{
		OOLogWARN(@"shipData.load.warning.flasher.badSize", @"skipping flasher of invalid size %g for ship %@.", size, shipKey);
		return nil;
	}

	brightfraction = [declaration oo_floatForKey:@"bright_fraction" defaultValue:0.5];
	if (brightfraction < 0.0 || brightfraction > 1.0)
	{
		OOLogWARN(@"shipData.load.warning.flasher.badFraction", @"skipping flasher of invalid bright fraction %g for ship %@.", brightfraction, shipKey);
		return nil;
	}
	
	frequency = [declaration oo_floatForKey:@"frequency" defaultValue:2.0];
	phase = [declaration oo_floatForKey:@"phase" defaultValue:0.0];
	initiallyOn = [declaration oo_boolForKey:@"initially_on" defaultValue:YES];
	
	result = [NSMutableDictionary dictionaryWithCapacity:8];
	[result setObject:@"flasher" forKey:@"type"];
	[result setObject:colors forKey:@"colors"];
	[result oo_setVector:position forKey:@"position"];
	[result setObject:[NSNumber numberWithFloat:size] forKey:@"size"];
	[result setObject:[NSNumber numberWithFloat:frequency] forKey:@"frequency"];
	if (phase != 0)  [result setObject:[NSNumber numberWithFloat:phase] forKey:@"phase"];
	[result setObject:[NSNumber numberWithFloat:brightfraction] forKey:@"bright_fraction"];
	[result setObject:[NSNumber numberWithBool:initiallyOn] forKey:@"initially_on"];
	
	return [[result copy] autorelease];
}


- (NSDictionary *) validateNewStyleStandardSubentityDeclaration:(NSDictionary *)declaration
														forShip:(NSString *)shipKey
													 fatalError:(BOOL *)outFatalError
{
	NSMutableDictionary		*result = nil;
	NSString				*subentityKey = nil;
	Vector					position = kZeroVector;
	Quaternion				orientation = kIdentityQuaternion;
	BOOL					isTurret;
	BOOL					isDock = NO;
	float					fireRate = -1.0f; // out of range constants
	float					weaponRange = -1.0f;
	float					weaponEnergy = -1.0f;
	NSDictionary			*scriptInfo = nil;
	
	subentityKey = [declaration objectForKey:@"subentity_key"];
	if (subentityKey == nil)
	{
		OOLogERR(@"shipData.load.error.badSubentity", @"subentity declaration for ship %@ specifies no subentity_key.", shipKey);
		*outFatalError = YES;
		return nil;
	}
	
	isTurret = [[declaration oo_stringForKey:@"type"] isEqualToString:@"ball_turret"];
	if (isTurret)
	{
		fireRate = [declaration oo_floatForKey:@"fire_rate" defaultValue:-1.0f];
		if (fireRate < 0.25f && fireRate >= 0.0f)
		{
			OOLogWARN(@"shipData.load.warning.turret.badFireRate", @"ball turret fire rate of %g for subentity of ship %@ is invalid, using 0.25.", fireRate, shipKey);
			fireRate = 0.25f;
		}
		weaponRange = [declaration oo_floatForKey:@"weapon_range" defaultValue:-1.0f];
		if (weaponRange > TURRET_SHOT_RANGE * COMBAT_WEAPON_RANGE_FACTOR)
		{
			OOLogWARN(@"shipData.load.warning.turret.badWeaponRange", @"ball turret weapon range of %g for subentity of ship %@ is too high, using %.1f.", weaponRange, shipKey, TURRET_SHOT_RANGE * COMBAT_WEAPON_RANGE_FACTOR);
			weaponRange = TURRET_SHOT_RANGE * COMBAT_WEAPON_RANGE_FACTOR; // approx. range of primary plasma canon.
		}

		weaponEnergy = [declaration oo_floatForKey:@"weapon_energy" defaultValue:-1.0f];
		if (weaponEnergy > 100.0f)
			
		{
			OOLogWARN(@"shipData.load.warning.turret.badWeaponEnergy", @"ball turret weapon energy of %g for subentity of ship %@ is too high, using 100.", weaponEnergy, shipKey);
			weaponEnergy = 100.0f;
		}
	}
	else
	{
		isDock = [declaration oo_boolForKey:@"is_dock"];
	}
	
	position = [declaration oo_vectorForKey:@"position"];
	orientation = [declaration oo_quaternionForKey:@"orientation"];
	quaternion_normalize(&orientation);
	
	scriptInfo = [declaration oo_dictionaryForKey:@"script_info"];
	
	result = [NSMutableDictionary dictionaryWithCapacity:10];
	[result setObject:isTurret ? @"ball_turret" : @"standard" forKey:@"type"];
	[result setObject:subentityKey forKey:@"subentity_key"];
	[result oo_setVector:position forKey:@"position"];
	[result oo_setQuaternion:orientation forKey:@"orientation"];
	if (isDock) 
	{
		[result oo_setBool:YES forKey:@"is_dock"];

		NSString* docklabel = [declaration oo_stringForKey:@"dock_label" defaultValue:@"the docking bay"];
		[result setObject:docklabel forKey:@"dock_label"];

		BOOL dockable = [declaration oo_boolForKey:@"allow_docking" defaultValue:YES];
		BOOL playerdockable = [declaration oo_boolForKey:@"disallowed_docking_collides" defaultValue:NO];
		BOOL undockable = [declaration oo_boolForKey:@"allow_launching" defaultValue:YES];

		[result oo_setBool:dockable forKey:@"allow_docking"];
		[result oo_setBool:playerdockable forKey:@"disallowed_docking_collides"];
		[result oo_setBool:undockable forKey:@"allow_launching"];

	}

	if (isTurret)
	{
		// default constants are defined and set in shipEntity
		if (fireRate > 0) [result oo_setFloat:fireRate forKey:@"fire_rate"];
		if (weaponRange >= 0) [result oo_setFloat:weaponRange forKey:@"weapon_range"];
		if (weaponEnergy >= 0) [result oo_setFloat:weaponEnergy forKey:@"weapon_energy"];
	}
	
	if (scriptInfo != nil)
	{
		[result setObject:scriptInfo forKey:@"script_info"];
	}
	
	return [[result copy] autorelease];
}


- (BOOL) shipIsBallTurretForKey:(NSString *)shipKey inShipData:(NSDictionary *)shipData
{
	// Test for presence of setup_actions containing initialiseTurret.
	NSArray					*setupActions = nil;
	NSEnumerator			*actionEnum = nil;
	NSString				*action = nil;
	
	setupActions = [[shipData oo_dictionaryForKey:shipKey] oo_arrayForKey:@"setup_actions"];
	
	for (actionEnum = [setupActions objectEnumerator]; (action = [actionEnum nextObject]); )
	{
		if ([[ScanTokensFromString(action) objectAtIndex:0] isEqualToString:@"initialiseTurret"])  return YES;
	}
	
	if ([shipKey isEqualToString:@"ballturret"])
	{
		// compatibility for OXPs using old subentity declarations and the
		// core turret entity
		return YES;
	}

	return NO;
}

@end


@implementation OOShipRegistry (Singleton)

/*	Canonical singleton boilerplate.
	See Cocoa Fundamentals Guide: Creating a Singleton Instance.
	See also +sharedRegistry above.
	
	NOTE: assumes single-threaded access.
*/

+ (id) allocWithZone:(NSZone *)inZone
{
	if (sSingleton == nil)
	{
		OOLog(@"shipData.load.begin", @"%@", @"Loading ship data.");
		sSingleton = [super allocWithZone:inZone];
		return sSingleton;
	}
	return nil;
}


- (id) copyWithZone:(NSZone *)inZone
{
	return self;
}


- (id) retain
{
	return self;
}


- (NSUInteger) retainCount
{
	return UINT_MAX;
}


- (void) release
{}


- (id) autorelease
{
	return self;
}

@end


static void GatherStringAddrsDict(NSDictionary *dict, NSMutableSet *strings, NSString *context);
static void GatherStringAddrsArray(NSArray *array, NSMutableSet *strings, NSString *context);
static void GatherStringAddrs(id object, NSMutableSet *strings, NSString *context);


static void DumpStringAddrs(NSDictionary *dict, NSString *context)
{
	return;
	static FILE *dump = NULL;
	if (dump == NULL)  dump = fopen("strings.txt", "w");
	if (dump == NULL)  return;
	
	NSAutoreleasePool *pool = [NSAutoreleasePool new];
	NSMutableSet *strings = [NSMutableSet set];
	GatherStringAddrs(dict, strings, context);
	
	NSEnumerator *entryEnum = nil;
	NSDictionary *entry = nil;
	for (entryEnum = [strings objectEnumerator]; (entry = [entryEnum nextObject]); )
	{
		NSString *string = [entry objectForKey:@"string"];
		NSString *context = [entry objectForKey:@"context"];
		void *pointer = [[entry objectForKey:@"address"] pointerValue];
		
		string = [NSString stringWithFormat:@"%p\t%@:  \"%@\"", pointer, context, string];
		
		fprintf(dump, "%s\n", [string UTF8String]);
	}
	
	fprintf(dump, "\n");
	fflush(dump);
	[pool release];
}


static void GatherStringAddrsDict(NSDictionary *dict, NSMutableSet *strings, NSString *context)
{
	NSEnumerator *keyEnum = nil;
	id key = nil;
	NSString *keyContext = [context stringByAppendingString:@" key"];
	for (keyEnum = [dict keyEnumerator]; (key = [keyEnum nextObject]); )
	{
		GatherStringAddrs(key, strings, keyContext);
		GatherStringAddrs([dict objectForKey:key], strings, [context stringByAppendingFormat:@".%@", key]);
	}
}


static void GatherStringAddrsArray(NSArray *array, NSMutableSet *strings, NSString *context)
{
	NSEnumerator *vEnum = nil;
	NSString *v = nil;
	unsigned i = 0;
	for (vEnum = [array objectEnumerator]; (v = [vEnum nextObject]); )
	{
		GatherStringAddrs(v, strings, [context stringByAppendingFormat:@"[%u]", i++]);
	}
}


static void GatherStringAddrs(id object, NSMutableSet *strings, NSString *context)
{
	if ([object isKindOfClass:[NSString class]])
	{
		NSDictionary *entry = [NSDictionary dictionaryWithObjectsAndKeys:object, @"string", [NSValue valueWithPointer:object], @"address", context, @"context", nil];
		[strings addObject:entry];
	}
	else if ([object isKindOfClass:[NSArray class]])
	{
		GatherStringAddrsArray(object, strings, context);
	}
	else if ([object isKindOfClass:[NSDictionary class]])
	{
		GatherStringAddrsDict(object, strings, context);
	}
}


static NSComparisonResult SortDemoShipsByName (id a, id b, void* context)
{
	return [[a oo_stringForKey:@"name"] compare:[b oo_stringForKey:@"name"]];
}


static NSComparisonResult SortDemoCategoriesByName (id a, id b, void* context)
{
	return [OOShipLibraryCategoryPlural([[a oo_dictionaryAtIndex:0] oo_stringForKey:@"class"]) compare:OOShipLibraryCategoryPlural([[b oo_dictionaryAtIndex:0] oo_stringForKey:@"class"])];
}