Difference between revisions of "DSB/Events and System Functions"

From DmWiki
Jump to navigationJump to search
(New page: == System Functions == When certain things happen globally, or values are needed, the game engine will call <b>sys_</b> functions. <small> All of them are contained in <i>base/system.lua<...)
 
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== System Functions ==
 
== System Functions ==
 
When certain things happen globally, or values are needed, the game engine will call <b>sys_</b> functions.
 
When certain things happen globally, or values are needed, the game engine will call <b>sys_</b> functions.
 +
 +
;<b>sys_render_other</b>(gui_name)
 +
:Add a new table to gui_info, like this:
 +
:<code>
 +
  gui_info.my_new_graphic = {
 +
      x = 20,
 +
      y = 100,
 +
      w = 200,
 +
      h = 96
 +
  }</code>
 +
:When <i>sys_render_other</i> is called, the <i>gui_name</i> parameter will be a string containing "my_new_graphic" or whatever you called the table.
 +
 +
;<b>sys_tick_second</b>(???)
 +
:Event for ticking in real-world seconds.
 +
 +
;<b>sys_inst_hit</b>(???)
 +
:For when the party collides with an object.
  
 
<small>
 
<small>
Line 10: Line 27:
  
 
;<b>on_throw</b>(self, id, location)
 
;<b>on_throw</b>(self, id, location)
:The '''location''' is where the object is thrown "from," via an attack method. It is '''nil''' if the object is thrown from the mouse hand. In that case, if you need to assume the throw came from some inventory zone, you can use the global variable <b>mouse''throwing''hand</b>.
+
:The '''location''' is where the object is thrown "from," via an attack method. It is '''nil''' if the object is thrown from the mouse hand. In that case, if you need to assume the throw came from some inventory zone, you can use the global variable <b>mouse_throwing_hand</b>.
:See also <i>base/methods.lua</i>: <b>method''throw''obj</b>.
+
:See also <i>base/methods.lua</i>: <b>method_throw_obj</b>.
  
;<b>on''impact</b>(self, id, hit''what, hit''ppos, hit''party)
+
;<b>on_impact</b>(self, id, hit_what, hit_ppos)
:This function is called when an inst hits something. If it hits a monster or object, <b>hit''what</b> will be set to an inst id. If it hits a party member, <b>hit''what</b> will be <b>nil</b>, <b>hit''ppos</b> will be the party position that it hit, and <b>hit''party</b> will be the party that was hit (which can be ignored in most cases)
+
:This function is called when an inst hits something. If it hits a monster or object, <b>hit_what</b> will be set to an inst id. If it hits a party member, <b>hit_what</b> will be <b>nil</b>, <b>hit_ppos</b> will be the party position that it hit.
:See also <i>base/damage.lua</i>: '''explode''thing''', '''poisonbomb''thing''', etc.
+
:See also <i>base/damage.lua</i>: '''explode_thing''', '''poisonbomb_thing''', etc.
  
 
;<b>on_deplete</b>(self, id)
 
;<b>on_deplete</b>(self, id)
:When an inst with charges consumes its last charge, this event is called. If this event doesn't exist, but the arch has a '''convert''deplete''' property, a '''dsb''swap''' is executed. Otherwise, the object is deleted.
+
:When an inst with charges consumes its last charge, this event is called. If this event doesn't exist, but the arch has a '''convert_deplete''' property, a '''dsb_swap''' is executed. Otherwise, the object is deleted.
  
;<b>on''click</b>(self, id, clicked''with, cx, cy)
+
;<b>on_click</b>(self, id, clicked_with, cx, cy)
 
:Used on a mirror, or a compass. The cx and cy values are the exact coordinates (relative to the upper left corner of the object's bitmap) that you clicked on, making it possible to define custom "click zones" with a bit of hacking.
 
:Used on a mirror, or a compass. The cx and cy values are the exact coordinates (relative to the upper left corner of the object's bitmap) that you clicked on, making it possible to define custom "click zones" with a bit of hacking.
  
;<b>on''look</b>(self, id, whose''eye) = new_id
+
;<b>on_look</b>(self, id, whose_eye) = new_id
 
:This is called when you click on someone's eye with an inst. If it returns an id, that id is shown, instead of the one actually held to the eye.
 
:This is called when you click on someone's eye with an inst. If it returns an id, that id is shown, instead of the one actually held to the eye.
  
Line 29: Line 46:
 
:Called when an inst is dropped. If it returns true, the inst can't be dropped.
 
:Called when an inst is dropped. If it returns true, the inst can't be dropped.
  
;<b>on''zone''drop</b>(self, drop''zone''id, dropped''obj''id)
+
;<b>on_zone_drop</b>(self, drop_zone_id, dropped_obj_id)
 
:Called when an inst is dropped into a drop zone (i.e., an alcove). If it returns true, the alcove won't accept the inst.
 
:Called when an inst is dropped into a drop zone (i.e., an alcove). If it returns true, the alcove won't accept the inst.
  
;<b>on''trigger</b>(self, id, trigger''id)
+
;<b>on_trigger</b>(self, id, trigger_id)
 
:Called when something is put on a flooritem. (If trigger_id is nil, it's the party)
 
:Called when something is put on a flooritem. (If trigger_id is nil, it's the party)
  
;<b>off''trigger</b>(self, id, trigger''id)
+
;<b>off_trigger</b>(self, id, trigger_id)
 
:Called when something comes off a flooritem. (If trigger_id is nil, it's the party)
 
:Called when something comes off a flooritem. (If trigger_id is nil, it's the party)
  
Line 42: Line 59:
  
 
;<b>on_fly</b>(id, x, y, tile, face, flytimer)
 
;<b>on_fly</b>(id, x, y, tile, face, flytimer)
:Used in the ''test''dungeon_, see crazy axe.
+
:Used in the '''test_dungeon''', see crazy axe.
  
 
;<b>on_consume</b>
 
;<b>on_consume</b>
Line 50: Line 67:
 
:Fired when created, such as a monster death cloud of dust.
 
:Fired when created, such as a monster death cloud of dust.
  
Also for the inventory there are events such as <code><b>to''feet</b>(id, who)</code>, <code><b>from''feet</b>(id, who)</code>, <code><b>to''neck</b>(id, who)</code>, <code><b>from''neck</b>(id, who)</code>, <code><b>to''r''hand</b></code>, <code><b>from''r''hand</b></code>, <code><b>to''l''hand</b></code>, <code><b>from''l''hand</b></code> and I just found <code><b>after''from''r''hand</b></code> and <code><b>after''from''l''hand</b></code> which pleases me greatly... Where I've finally found a <code><b>to''anywhere</b></code> and <code><b>from''anywhere</b></code> event.
+
;<b>on_melee_damage_monster</b>
 +
:An event for hooking attack methods of specific weapons
 +
 
 +
;<b>on_monster_move_into</b>
 +
:Event for objects that handle monster movement in special ways.
 +
 
 +
;<b>on_teleport</b>
 +
:Called when teleporting the object.
 +
 
 +
;<b>on_incoming_impact</b>(arch, inst, flying_inst)
 +
:Take a look at ''monster_dodge'' in ''base/monster.lua'' for the code that makes monsters hurriedly rearrange themselves on the tile if a projectile is about to hit them and there's somewhere to go.
 +
 
 +
Also for the inventory there are events such as <code><b>to_feet</b>(id, who)</code>, <code><b>from_feet</b>(id, who)</code>, <code><b>to_neck</b>(id, who)</code>, <code><b>from_neck</b>(id, who)</code>, <code><b>to_r_hand</b></code>, <code><b>from_r_hand</b></code>, <code><b>to_l_hand</b></code>, <code><b>from_l_hand</b></code> and I just found <code><b>after_from_r_hand</b></code> and <code><b>after_from_l_hand</b></code> which pleases me greatly... Where I've finally found a <code><b>to_anywhere</b></code> and <code><b>from_anywhere</b></code> event.
  
Not an 'event' as such but we also have <code><b>flying''away</b></code>, <code><b>flying''toward</b></code>, <code><b>flying_side</b></code> properties to assign if necessary for a bitmap.
+
Not an 'event' as such but we also have <code><b>flying_away</b></code>, <code><b>flying_toward</b></code>, <code><b>flying_side</b></code> properties to assign if necessary for a bitmap.
  
;<b>potion''effect</b>(id, who, base''power)
+
;<b>potion_effect</b>(id, who, base_power)
 
:Create your own potions and effects.
 
:Create your own potions and effects.
  
Line 66: Line 95:
 
:Yeah, this is a good one... See the objects.lua
 
:Yeah, this is a good one... See the objects.lua
  
;<b>objzone''check</b>(id, putting''in, zone)
+
;<b>objzone_check</b>(id, putting_in, zone)
 
:See the objects.lua
 
:See the objects.lua
  
Things such as stairs are objects of course and have events such as <code><b>on''trigger</b></code>, <code><b>off''trigger</b></code>, <code><b>on''turn</b></code>, <code><b>on''try_move</b></code>, ...
+
Things such as stairs are objects of course and have events such as <code><b>on_trigger</b></code>, <code><b>off_trigger</b></code>, <code><b>on_turn</b></code>, <code><b>on_try_move</b></code>, ...
  
  
[[Category:DSB]]
+
[[Category:DSB|Events and System Functions]]

Latest revision as of 16:55, 20 August 2014

System Functions

When certain things happen globally, or values are needed, the game engine will call sys_ functions.

sys_render_other(gui_name)
Add a new table to gui_info, like this:
  gui_info.my_new_graphic = {
     x = 20,
     y = 100,
     w = 200,
     h = 96
  }
When sys_render_other is called, the gui_name parameter will be a string containing "my_new_graphic" or whatever you called the table.
sys_tick_second(???)
Event for ticking in real-world seconds.
sys_inst_hit(???)
For when the party collides with an object.

All of them are contained in base/system.lua (except for the rendering-related ones, in base/render.lua), so look there for now. If anyone wants to wiki-ize the list, feel free. I'll be working mostly on things that I haven't documented somewhere else. -- Sophia

Events

When certain things happen to a specific object, the game engine (or, sometimes, the Base Code) will call various events associated with an object arch.

on_throw(self, id, location)
The location is where the object is thrown "from," via an attack method. It is nil if the object is thrown from the mouse hand. In that case, if you need to assume the throw came from some inventory zone, you can use the global variable mouse_throwing_hand.
See also base/methods.lua: method_throw_obj.
on_impact(self, id, hit_what, hit_ppos)
This function is called when an inst hits something. If it hits a monster or object, hit_what will be set to an inst id. If it hits a party member, hit_what will be nil, hit_ppos will be the party position that it hit.
See also base/damage.lua: explode_thing, poisonbomb_thing, etc.
on_deplete(self, id)
When an inst with charges consumes its last charge, this event is called. If this event doesn't exist, but the arch has a convert_deplete property, a dsb_swap is executed. Otherwise, the object is deleted.
on_click(self, id, clicked_with, cx, cy)
Used on a mirror, or a compass. The cx and cy values are the exact coordinates (relative to the upper left corner of the object's bitmap) that you clicked on, making it possible to define custom "click zones" with a bit of hacking.
on_look(self, id, whose_eye) = new_id
This is called when you click on someone's eye with an inst. If it returns an id, that id is shown, instead of the one actually held to the eye.
on_drop(self, id)
Called when an inst is dropped. If it returns true, the inst can't be dropped.
on_zone_drop(self, drop_zone_id, dropped_obj_id)
Called when an inst is dropped into a drop zone (i.e., an alcove). If it returns true, the alcove won't accept the inst.
on_trigger(self, id, trigger_id)
Called when something is put on a flooritem. (If trigger_id is nil, it's the party)
off_trigger(self, id, trigger_id)
Called when something comes off a flooritem. (If trigger_id is nil, it's the party)
on_turn(self, id, dir)
Useful for the compass, for example.
on_fly(id, x, y, tile, face, flytimer)
Used in the test_dungeon, see crazy axe.
on_consume
See function eatdrink, where you need to set a foodval or waterval property for the arch type.
on_spawn
Fired when created, such as a monster death cloud of dust.
on_melee_damage_monster
An event for hooking attack methods of specific weapons
on_monster_move_into
Event for objects that handle monster movement in special ways.
on_teleport
Called when teleporting the object.
on_incoming_impact(arch, inst, flying_inst)
Take a look at monster_dodge in base/monster.lua for the code that makes monsters hurriedly rearrange themselves on the tile if a projectile is about to hit them and there's somewhere to go.

Also for the inventory there are events such as to_feet(id, who), from_feet(id, who), to_neck(id, who), from_neck(id, who), to_r_hand, from_r_hand, to_l_hand, from_l_hand and I just found after_from_r_hand and after_from_l_hand which pleases me greatly... Where I've finally found a to_anywhere and from_anywhere event.

Not an 'event' as such but we also have flying_away, flying_toward, flying_side properties to assign if necessary for a bitmap.

potion_effect(id, who, base_power)
Create your own potions and effects.
hit_sound
Used for weapons, assigning a sound.
namechanger(id, who_look)
Used with the bones object or a Ven Bomb for example.
subrenderer(id)
Yeah, this is a good one... See the objects.lua
objzone_check(id, putting_in, zone)
See the objects.lua

Things such as stairs are objects of course and have events such as on_trigger, off_trigger, on_turn, on_try_move, ...