Horian
Member
Backup from ArteGordon from http://xmlspawner.fr.yuku.com/topic/50/What-are-Attachments
What are attachments?
The attachment system allows dynamic functionality to be added to items/mobs without requiring any modification to the item/mob scripts themselves. Think of them as something like scripted "post-its" that can be stuck onto any item or mob, and can then give them new user-scriptable abilities. Multiple attachments can be added to targets.
All of the addon systems use this system and because of this, they require no modifications to any existing mobile, item, or playermobile scripts. Using this system, you never have to modify the Serialization of any object.
For example, placing the simple xmlhue attachment onto a mobile allows you to change its hue for some duration, after which it gets changed back to its original hue. In order to do this conventionally you would have to modify the playermobile script with additional variables, serialization/deserialization, timers, etc. If you also wanted to be able to do the same thing for creatures, you would have to add the same mods to basecreature, armor... basearmor, etc. With attachments, you can add the hue changing ability to any item or mob with no script modification of the target class. This includes things that are derived directly from inaccessible classes such as statics.
Commands:
- several commands are available for staff support of attachments.
[addatt attachmenttype [args] - allows attachments of the specified type to be added to targeted objects. For example, to have a door display a message whenever it is approached, you could do "[addatt xmlmessage Welcome!". To also have a sound played you could add "[addatt xmlsound 1048"
[getatt [type] - allows the attachments on a targeted object to be listed. If the optional type argument is given, then only attachments of that type are displayed.
[delatt [type][serial] - allows attachments on a targeted object to be deleted. If no arguments are given, then all attachments on the object are deleted. If the type is specified, then only attachments of that type are deleted. If a serial number is specified, then the specific attachment with that serial number is deleted (use [getatt to see the serial numbers).
[availatt - opens a gump that lists all of the available attachments and their various constructors and arguments. All constructors for objects derived from the XmlAttachment class and flagged with the [Attachable] attribute will be listed.
InGame Support:
- a checkbox in the [xmlfind gump allows searching for items/mobs with attachments. If the attach box is selected, then an additional filter for objects with attachments associated with them will be applied.
- using the ATTACH keyword in spawn entries allows attachments to be added to spawned items/mobs.
It is very similar to the ADD keyword, but instead of adding items, you add attachments.
The syntax is
ATTACH[,probability]/attachmenttype
If you further wish to set properties on the attachment that you are adding, you would use the syntax
ATTACH[,probability]/<attachmenttype/prop/value/prop/value...>
For example, the xmlmagicword attachment has a requireidentification property that can be set, that forces players to identify the attachment before it can be used. This property can be set at spawn time with
ATTACH/<xmlmagicword/requireidentification/true>
See attachtest2.xml for an example.
- the GET series of keywords (this includes GET, GETONMOB, GETONTRIGMOB, GETONCARRIED, GETONSPAWN) supports retrieving properties from attachments .
Whereever a property would normally be specified for those keywords, the new property keyword <ATTACHMENT,type,name,property> can be used. For example, to read the value property on an xmlvalue attachment with the name XS on a triggering mob you would specify
GETONTRIGMOB,<ATTACHMENT,xmlvalue,XS,value>
(See attachtest1.xml for examples).
- spawner triggering can be made dependent upon attachments on the triggering mob by using the "ATTACHMENT,name,type" string in the TriggerOnCarried or NoTriggerOnCarried properties.
This will make triggering dependent on attachments on the mob, or an attachment on an item equipped by the mob, or an attachment on an item in the top level of the mobs backpack (see attachtest1.xml for an example).
- attachments can also be used as quest rewards by specifying them in the RewardString of a questholder or questnote just as you would in the ATTACH keyword.
You should also enable autoreward to have them automatically applied on quest completion. They will be displayed as a "Bonus:" in the quest gump. The details of the attachment cannot be queried at the moment, but I will add that capability (See minionstrike.xml for an example)
- attachments are scripted and have class definitions that look similar to items or mobiles.
Users can script their own attachments in much the same way that they would script new items or mobs. All attachments are derived from the XmlAttachment class that implements the IXmlAttachment interface. This interface defines support for several features that all attachments have access to, including activation on movement, speech, and weapon hits (see XmlAttachment.cs for the interface specification). See the XmlAttachments folder for example scripts.
- attachments can also be used in other scripts by simply creating new instances of the attachments (e.g. XmlAttachment attachment = new XmlHue(200); ) and then applying them to the target with AttachTo(targetobject, attachment);
Note, that the attachment is achieved via an object/attachment hash table association, so there is no actual modification of the targetobject.
- all attachments are maintained in hashtables that are serialized separately from the item and mobile tables. The save information for attachments can be found in the Saves/Attachments folder.
- attachments support activation via speech or movement using the OnSpeech and OnMovement methods that can be defined in any attachment script.
This is accomplished by adding additional speech and movement event handlers. I have done extensive stress test profiling of these handlers up to loads equivalent to 10,000 simultaneous players and have calculated the additional overhead to be around a maximum of 1-3% additional cpu overhead for movement at 10K players, and less than 0.1% for speech, with a proportional decrease in load with fewer players. While it is highly unlikely that anyone would notice any impact of these handlers, they can be disabled if desired (of course, speech/movement attachment triggering will also be disabled) by simply commenting out the EventSink.Speech and EventSink.Movement handler lines in the Initialize method of XmlAttach in XmlAttach.cs.
What are attachments?
The attachment system allows dynamic functionality to be added to items/mobs without requiring any modification to the item/mob scripts themselves. Think of them as something like scripted "post-its" that can be stuck onto any item or mob, and can then give them new user-scriptable abilities. Multiple attachments can be added to targets.
All of the addon systems use this system and because of this, they require no modifications to any existing mobile, item, or playermobile scripts. Using this system, you never have to modify the Serialization of any object.
For example, placing the simple xmlhue attachment onto a mobile allows you to change its hue for some duration, after which it gets changed back to its original hue. In order to do this conventionally you would have to modify the playermobile script with additional variables, serialization/deserialization, timers, etc. If you also wanted to be able to do the same thing for creatures, you would have to add the same mods to basecreature, armor... basearmor, etc. With attachments, you can add the hue changing ability to any item or mob with no script modification of the target class. This includes things that are derived directly from inaccessible classes such as statics.
Commands:
- several commands are available for staff support of attachments.
[addatt attachmenttype [args] - allows attachments of the specified type to be added to targeted objects. For example, to have a door display a message whenever it is approached, you could do "[addatt xmlmessage Welcome!". To also have a sound played you could add "[addatt xmlsound 1048"
[getatt [type] - allows the attachments on a targeted object to be listed. If the optional type argument is given, then only attachments of that type are displayed.
[delatt [type][serial] - allows attachments on a targeted object to be deleted. If no arguments are given, then all attachments on the object are deleted. If the type is specified, then only attachments of that type are deleted. If a serial number is specified, then the specific attachment with that serial number is deleted (use [getatt to see the serial numbers).
[availatt - opens a gump that lists all of the available attachments and their various constructors and arguments. All constructors for objects derived from the XmlAttachment class and flagged with the [Attachable] attribute will be listed.
InGame Support:
- a checkbox in the [xmlfind gump allows searching for items/mobs with attachments. If the attach box is selected, then an additional filter for objects with attachments associated with them will be applied.
- using the ATTACH keyword in spawn entries allows attachments to be added to spawned items/mobs.
It is very similar to the ADD keyword, but instead of adding items, you add attachments.
The syntax is
ATTACH[,probability]/attachmenttype
If you further wish to set properties on the attachment that you are adding, you would use the syntax
ATTACH[,probability]/<attachmenttype/prop/value/prop/value...>
For example, the xmlmagicword attachment has a requireidentification property that can be set, that forces players to identify the attachment before it can be used. This property can be set at spawn time with
ATTACH/<xmlmagicword/requireidentification/true>
See attachtest2.xml for an example.
- the GET series of keywords (this includes GET, GETONMOB, GETONTRIGMOB, GETONCARRIED, GETONSPAWN) supports retrieving properties from attachments .
Whereever a property would normally be specified for those keywords, the new property keyword <ATTACHMENT,type,name,property> can be used. For example, to read the value property on an xmlvalue attachment with the name XS on a triggering mob you would specify
GETONTRIGMOB,<ATTACHMENT,xmlvalue,XS,value>
(See attachtest1.xml for examples).
- spawner triggering can be made dependent upon attachments on the triggering mob by using the "ATTACHMENT,name,type" string in the TriggerOnCarried or NoTriggerOnCarried properties.
This will make triggering dependent on attachments on the mob, or an attachment on an item equipped by the mob, or an attachment on an item in the top level of the mobs backpack (see attachtest1.xml for an example).
- attachments can also be used as quest rewards by specifying them in the RewardString of a questholder or questnote just as you would in the ATTACH keyword.
You should also enable autoreward to have them automatically applied on quest completion. They will be displayed as a "Bonus:" in the quest gump. The details of the attachment cannot be queried at the moment, but I will add that capability (See minionstrike.xml for an example)
- attachments are scripted and have class definitions that look similar to items or mobiles.
Users can script their own attachments in much the same way that they would script new items or mobs. All attachments are derived from the XmlAttachment class that implements the IXmlAttachment interface. This interface defines support for several features that all attachments have access to, including activation on movement, speech, and weapon hits (see XmlAttachment.cs for the interface specification). See the XmlAttachments folder for example scripts.
- attachments can also be used in other scripts by simply creating new instances of the attachments (e.g. XmlAttachment attachment = new XmlHue(200); ) and then applying them to the target with AttachTo(targetobject, attachment);
Note, that the attachment is achieved via an object/attachment hash table association, so there is no actual modification of the targetobject.
- all attachments are maintained in hashtables that are serialized separately from the item and mobile tables. The save information for attachments can be found in the Saves/Attachments folder.
- attachments support activation via speech or movement using the OnSpeech and OnMovement methods that can be defined in any attachment script.
This is accomplished by adding additional speech and movement event handlers. I have done extensive stress test profiling of these handlers up to loads equivalent to 10,000 simultaneous players and have calculated the additional overhead to be around a maximum of 1-3% additional cpu overhead for movement at 10K players, and less than 0.1% for speech, with a proportional decrease in load with fewer players. While it is highly unlikely that anyone would notice any impact of these handlers, they can be disabled if desired (of course, speech/movement attachment triggering will also be disabled) by simply commenting out the EventSink.Speech and EventSink.Movement handler lines in the Initialize method of XmlAttach in XmlAttach.cs.