User:Ivan/Configurable object

This page describes work-in-progress draft of support for configurable object that should replace majority of bonusing objects

Classes in process of replacing

• CGPickable
• CGBonusingObject
• CGOnceVisitable
• CGVisitableOPH
• CGVisitableOPW
• CGMagicSpring

Reward limiters

Requirements that must be fulfilled by visitor to receive reward

	/// how many times this reward can be granted, 0 for unlimited
	int numOfGrants;

	/// day of week, unused if 0, 1-7 will test for current day of week
	int dayOfWeek;

	/// resources player needs to have in order to trigger reward
	TResources resources;

	/// skills hero needs to have
	std::vector<si32> primary;
	std::map<SecondarySkill, si32> secondary;

	/// artifacts that hero needs to have (equipped or in backpack) to trigger this
	std::vector<ArtifactID> artifacts;

	/// creatures that hero needs to have
	std::vector<CStackBasicDescriptor> creatures;

Note that right now these describe objects that visitor must have, these objects will not be removed unless removed as part of "reward" (or some other mechanism).

Rewardables

Object that visitor may receive (or lose, for negative amounts)

	/// resources that will be given to player
	TResources resources;

	/// received experience
	ui32 gainedExp;
	/// received levels (converted into XP during grant)
	ui32 gainedLevels;
	/// mana given to/taken from hero
	si32 manaDiff;
	/// movement points, only for current day. Bonuses should be used to grant MP on any other day
	si32 movePoints;
	/// list of bonuses, e.g. morale/luck
	std::vector<Bonus> bonuses;

	/// skills that hero may receive or lose
	std::vector<si32> primary;
	std::map<SecondarySkill, si32> secondary;

	/// objects that hero may receive
	std::vector<ArtifactID> artifacts;
	std::vector<SpellID> spells;
	std::vector<CStackBasicDescriptor> creatures;

Properties of rewardable object

	enum ESelectMode
	{
		SELECT_FIRST,  // first reward that matches limiters
		SELECT_PLAYER, // player can select from all allowed rewards
		SELECT_RANDOM, // reward will be selected from allowed randomly
		SELECT_ALL     // all available rewards will be granted to player
	};

	enum EVisitMode
	{
		VISIT_UNLIMITED, // any number of times
		VISIT_ONCE,      // only once, first to visit get all the rewards
		VISIT_HERO,      // every hero can visit object once
		VISIT_PLAYER     // every player can visit object once
	};

	/// MetaString's that contain text for messages for specific situations
	MetaString onGrant;
	MetaString onVisited;
	MetaString onEmpty;

	/// sound that will be played alongside with *any* message
	ui16 soundID;

	/// how reward will be selected, uses ESelectMode enum
	ui8 selectMode;
	/// contols who can visit an object, uses EVisitMode enum
	ui8 visitMode;

	/// object visitability info will be reset each resetDuration days
	ui16 resetDuration;

Note: this does not includes some internal members - only those that may become configurable

Not yet handled situations

• Some objects must be removed after visit
• Some objects block movement to visitable tile (blockVisit property)
• Different messages for different rewards (e.g. Stables)
• Auto-upgrade for stables (or keep it hardcoded)
• Possibility to refuse visit (e.g. Tomb)

Limitations

Known limitations of current approach, all of these are largely "works as intended", although may be changed in future if nice solution will be found.

• As of now it is impossible to specify *ranges* of possible rewards - their values must be fixed. Situations like Windmill (3-6 of random resource) can be implemented as large list of every possible reward.
• To properly handle cases like Tomb of Warrior and for H3-like selection of one reward from multiple (e.g. School of Magic) visitor will have to select reward based on one visible component of these rewards. This should result in behavior identical to H3 but may not work as desired for mod objects. Examples:
  • In Tomb visitor will have two "rewards": single-use "-3 morale + artifact" and multiple use "-3 morale". To hide actual reward from visitor only first component (-3 morale) will be visible in selection dialog for both cases.
  • In School of Magic player have two rewards to choice from "+1 to Spellpower and -1000 to gold" and "+1 to Knowledge and -1000 to gold". However only one component will be known to player (change to primary skill).
  • Note: AI will still be able to evaluate rewards properly based on generic object description, human player will be able to evaluate rewards only based on visit message and past experience.

Planned changes

Essential

• Move some properties to rewards (e.g. grant message)
• Finish rewrite of current set of objects
• Proper support for AI

Planned

• Extend system to support more objects:
  • Events/Pandora Boxes
  • Seer Huts/Quest Guards
  • Banks/Pyramid (at least for actual reward)

Possible

• Extend for several related objects:
  • Keymaster/Border Guards
  • Town buildings