Propriétés de script

Les propriétés de script offrent un moyen simple et puissant de définir et d’exposer des propriétés personnalisées pour une instance particulière d’objet de jeu (game object). Vous pouvez modifier les propriétés de script d’instances particulières directement dans l’éditeur et utiliser leurs valeurs dans le code pour modifier le comportement d’un objet de jeu. Les propriétés de script sont très utiles dans de nombreux cas :

• Lorsque vous souhaitez remplacer des valeurs pour des instances particulières dans l’éditeur et ainsi améliorer la réutilisabilité du script.
• Lorsque vous souhaitez créer un objet de jeu avec des valeurs initiales.
• Lorsque vous souhaitez animer les valeurs d’une propriété.
• Lorsque vous souhaitez accéder aux données d’état d’un script depuis un autre. (Notez que si vous accédez fréquemment aux propriétés entre objets, il peut être préférable de déplacer les données vers un stockage partagé.)

Les cas d’utilisation courants consistent à définir les points de vie ou la vitesse de l’IA d’un ennemi donné, la teinte d’un objet à ramasser, l’atlas d’un sprite ou le message qu’un objet bouton doit envoyer lorsqu’il est actionné—et/ou la destination de ce message.

Définir une propriété de script

Les propriétés de script sont ajoutées à un composant script en les définissant avec la fonction spéciale go.property(). Cette fonction doit être utilisée au niveau supérieur, en dehors de toute fonction du cycle de vie comme init() et update(). La valeur par défaut fournie détermine le type de la propriété : number, boolean, string, hash, msg.url, vmath.vector3, vmath.vector4, vmath.quaternion et resource (voir ci-dessous).

-- can.script
-- Define script properties for health and an attack target
go.property("health", 100)
go.property("target", msg.url())

function init(self)
  -- store initial position of target.
  -- self.target is a url referencing another object.
  self.target_pos = go.get_position(self.target)
  ...
end

function on_message(self, message_id, message, sender)
  if message_id == hash("take_damage") then
    -- decrease the health property
    self.health = self.health - message.damage
    if self.health <= 0 then
      go.delete()
    end
  end
end

Il est alors possible de définir les valeurs des propriétés pour toute instance de composant script créée à partir de ce script.

Sélectionnez le composant script dans la vue Outline de l’éditeur : les propriétés apparaissent dans la vue Properties, où vous pouvez les modifier :

Toute propriété dont la valeur est remplacée par une nouvelle valeur propre à l’instance est affichée en bleu. Cliquez sur le bouton de réinitialisation à côté du nom de la propriété pour rétablir la valeur par défaut (définie dans le script).

Propriétés textuelles

Depuis Defold 1.13.2, une valeur par défaut de type chaîne définit une propriété textuelle. Les propriétés textuelles prennent en charge UTF-8 et les caractères de saut de ligne et se modifient dans un champ multiligne de l’éditeur :

go.property("greeting", "Hello!\nWelcome, José!")

function init(self)
    go.set("#label", "text", self.greeting)
end

Sélectionnez un composant script dans un objet de jeu ou une collection pour remplacer les valeurs de ses propriétés textuelles, comme pour les autres propriétés de script. Les caractères NUL intégrés ne sont pas autorisés dans les valeurs par défaut ni dans les valeurs de remplacement.

D’autres scripts peuvent lire et écrire une propriété textuelle via l’URL du composant script. Par exemple, placez le script ci-dessus et un label dans un objet de jeu nommé speaker dans la collection, avec les identifiants de composants script et label. Mettez-les à jour depuis la fonction init() d’un autre script :

function init(self)
    local greeting = go.get("/speaker#script", "greeting")
    go.set("/speaker#script", "greeting", greeting .. "\nEnjoy the game!")
    go.set("/speaker#label", "text", go.get("/speaker#script", "greeting"))
end

Modifier la propriété du script ne met pas automatiquement le label à jour ; la dernière ligne copie explicitement la nouvelle valeur dans la propriété text du label.

Accéder aux propriétés de script

Toute propriété de script définie est disponible sous la forme d’un membre stocké dans self, la référence à l’instance du script :

-- my_script.script
go.property("my_property", 1)

function update(self, dt)
  -- Read and write the property
  if self.my_property == 1 then
      self.my_property = 3
  end
end

Les propriétés de script définies par l’utilisateur peuvent également être lues avec go.get() et écrites avec go.set(). Les propriétés numériques, y compris les vecteurs et les quaternions, peuvent être animées avec go.animate(). Les propriétés textuelles peuvent être lues et écrites, mais ne peuvent pas être animées :

-- another.script

-- increase "my_property" in "myobject#script" by 1
local val = go.get("myobject#my_script", "my_property")
go.set("myobject#my_script", "my_property", val + 1)

-- animate "my_property" in "myobject#my_script"
go.animate("myobject#my_script", "my_property", go.PLAYBACK_LOOP_PINGPONG, 100, go.EASING_LINEAR, 2.0)

Objets créés par une factory

Si vous utilisez une factory pour créer l’objet de jeu, vous pouvez définir les propriétés de script au moment de sa création :

local props = { health = 50, target = msg.url("player") }
local id = factory.create("#can_factory", nil, nil, props)

-- Accessing factory-created script properties
local url = msg.url(nil, id, "can")
local can_health = go.get(url, "health")

Lorsque vous créez une hiérarchie d’objets de jeu au moyen de collectionfactory.create(), vous devez associer les identifiants des objets à des tables de propriétés. Ces associations sont regroupées dans une table transmise à la fonction create() :

local props = {}
props[hash("/can1")] = { health = 150 }
props[hash("/can2")] = { health = 250, target = msg.url("player") }
props[hash("/can3")] = { health = 200 }

local ids = collectionfactory.create("#cangang_factory", nil, nil, props)

Les valeurs de propriétés fournies via factory.create() et collectionfactory.create() remplacent toute valeur définie dans le fichier prototype ainsi que les valeurs par défaut du script.

Si plusieurs composants script attachés à un objet de jeu définissent la même propriété, chaque composant sera initialisé avec la valeur fournie à factory.create() ou à collectionfactory.create().

Propriétés de ressources

Les propriétés de ressources se définissent de la même manière que les propriétés de script pour les types de données de base :

go.property("my_atlas", resource.atlas("/atlas.atlas"))
go.property("my_font", resource.font("/font.font"))
go.property("my_material", resource.material("/material.material"))
go.property("my_texture", resource.texture("/texture.png"))
go.property("my_tile_source", resource.tile_source("/tilesource.tilesource"))

Lorsqu’une propriété de ressource est définie, elle apparaît dans la vue Properties comme toute autre propriété de script, mais sous la forme d’un champ de sélection de fichier ou de ressource :

Vous accédez aux propriétés de ressources avec go.get() ou via self, la référence à l’instance du script, et vous les utilisez avec go.set() :

function init(self)
  go.set("#sprite", "image", self.my_atlas)
  go.set("#label", "font", self.my_font)
  go.set("#sprite", "material", self.my_material)
  go.set("#model", "texture0", self.my_texture)
  go.set("#tilemap", "tile_source", self.my_tile_source)
end