Difference between revisions of "Manual:DIL Manual/act()"

From DikuMUD Wiki
Jump to navigation Jump to search
(XML import of LLM wiki pages)
 
Line 1: Line 1:
−
= act =
 
  
−
The '''act''' function is a built-in DIL (DikuMUD Interactive Language) function that sends formatted messages to characters in a room or specific targets.
 
  
−
== Syntax ==
+
<span id="bpact"></span>
−
act(string message, integer visibility, unitptr char, unitptr medium, unitptr victim, integer to_whom)
 
  
−
== Parameters ==
+
The purpose of act is to send a message to a number of players '''present''' in
−
{| class="wikitable"
+
a room.  The room is defined as the room containing the afore mentioned
−
! Parameter !! Type !! Description
+
character (provided he himself is in the room, i.e. not in a closed
−
|-
+
container.)
−
| message || string || The message to be sent (with formatters)
 
−
|-
 
−
| visibility || integer || Visibility flag for message delivery
 
−
|-
 
−
| char || unitptr || The character performing the action (for $1, $2, etc.)
 
−
|-
 
−
| medium || unitptr || The medium/object being used (for $m)
 
−
|-
 
−
| victim || unitptr || The target of the action (for $3, $4, etc.)
 
−
|-
 
−
| to_whom || integer || Who receives the message (target audience)
 
−
|}
 
  
−
== Return Value ==
 
−
This function does not return a value (void).
 
  
−
== Visibility Flags ==
+
---~---~---~---~---~---~---~---~---
−
{| class="wikitable"
 
−
! Flag !! Value !! Description
 
−
|-
 
−
| A_SOMEONE || Send to character only
 
−
|-
 
−
| A_HIDEINV || Hide action from others in room
 
−
|-
 
−
| A_ALWAYS || Send to everyone regardless of visibility
 
−
|-
 
−
| A_SOMEONE || Send to character and room (excluding character)
 
−
|-
 
−
| A_NOTVICT || Send to everyone except victim
 
−
|-
 
−
| TO_CHAR || Send to character only
 
−
|-
 
−
| TO_VICT || Send to victim only
 
−
|-
 
−
| TO_ROOM || Send to room (excluding character)
 
−
|-
 
−
| TO_REST || Send to everyone except those fighting or resting
 
−
|-
 
−
| TO_ALL || Send to everyone in room
 
−
|}
 
  
−
== Message Formatters ==
+
'''Syntax:'''
−
The message string can contain special formatters that are replaced at runtime:
 
  
−
{| class="wikitable"
+
act(message, visibility, char, medium, victim, to_whom);
−
! Formatter !! Description !! Example
 
−
|-
 
−
| $1 || Replaced with character's name
 
−
|-
 
−
| $2 || Replaced with medium's name
 
−
|-
 
−
| $3 || Replaced with victim's name
 
−
|-
 
−
| $4 || Replaced with victim's title
 
−
|-
 
−
| $5 || Replaced with victim's name (gender-aware: he/she/it)
 
−
|-
 
−
| $6 || Replaced with victim's name (gender-aware: him/her/it)
 
−
|-
 
−
| $n || Replaced with victim's name (gender-aware: his/her/its)
 
−
|-
 
−
| $a || Replaced with victim's name (gender-aware: he/she/it)
 
−
|-
 
−
| $m || Replaced with victim's name (gender-aware: him/her/it)
 
−
|-
 
−
| $e || Replaced with victim's name (gender-aware: him/her/it)
 
−
|-
 
−
| $s || Replaced with victim's name (gender-aware: him/her/it)
 
−
|-
 
−
| $t || Replaced with victim's name (gender-aware: him/her/it)
 
−
|}
 
  
−
== Examples ==
 
−
=== Basic Action Message ===
 
−
dilbegin simple_action(actor : unitptr, target : unitptr);
 
−
code
 
−
{
 
−
    act("$1n picks up $2n.", A_SOMEONE, actor, null, target, TO_CHAR);
 
−
    act("$1n picks up $2n.", A_NOTVICT, actor, null, target, TO_ROOM);
 
−
    quit;
 
−
} dilend
 
  
−
=== Combat Message ===
+
<!--TERM--> '''message'''
−
  dilbegin combat_message(attacker : unitptr, defender : unitptr);
+
<!--DEFINITION-->          - is a string that will be shown to other mobiles when the act is executed. To refer to the following arguments use the [[#formatters|formatters]] listed below.
−
  code
+
  <!--TERM--> '''visibility'''
−
  {
+
  <!--DEFINITION-->          - is an integer that defines what happens if the mobile that is about to receive the message can't see the activator.
−
    act("$1n attacks $3n with deadly force!", A_ALWAYS, attacker, null, defender, TO_VICT);
+
  <!--TERM-->        <b><!--CODE-->A_SOMEONE</b><!--ENDCODE-->
−
    act("$1n attacks $3n with deadly force!", A_NOTVICT, attacker, null, defender, TO_ROOM);
+
<!--DEFINITION-->                If the receiver cannot see char, replace any reference to char with <i>someone</i>.
−
    quit;
+
<!--TERM-->        <b><!--CODE-->A_HIDEINV</b><!--ENDCODE-->
−
  } dilend
+
<!--DEFINITION-->                If the receiver cannot see char, don't send the message at all. Use this when missing vision should eliminate the perception of the action the message represent. One instance where it is used is in smile. You would need a ridiculously sensitive ear to hear, let alone percept that someone's smiling if you can't see them. Do not use it if 'sound' is inherent in the message.
 +
<!--TERM-->        <b><!--CODE-->A_ALWAYS</b><!--ENDCODE-->
 +
<!--DEFINITION-->                Works exactly like <i><!--CODE-->A_SOMEONE</i><!--ENDCODE-->, except that the receiver will see the message even when sleeping.
 +
<!--TERM--> '''char'''
 +
<!--DEFINITION-->          - is a unitptr, and the most important argument in the act. If this is not valid the act will never show, leaving mobiles without the message.
 +
<!--TERM--> '''medium'''
 +
<!--DEFINITION-->          - is a unit pointer, an integer or a string. Use this at your leisure.
 +
<!--TERM--> '''victim'''
 +
<!--DEFINITION-->          - is a unit pointer, an integer or a string. Certain flags in the next argument rely on the validity of victim.
 +
<!--TERM--> '''to_whom'''
 +
<!--DEFINITION-->          - is an integer that defines who gets the message.
 +
<!--TERM-->        <b><!--CODE-->TO_ROOM</b><!--ENDCODE-->
 +
<!--DEFINITION-->                Sends the message to the entire room, excluding 'char'.
 +
<!--TERM-->        <b><!--CODE-->TO_VICT</b><!--ENDCODE-->
 +
<!--DEFINITION-->                Sends to 'victim' only. 'victim' must be valid, naturally.
 +
<!--TERM-->        <b><!--CODE-->TO_NOTVICT</b><!--ENDCODE-->
 +
<!--DEFINITION-->                Sends the message to the entire room, excluding 'char' and 'victim'.  Perfect for bystanders in a melee.
 +
<!--TERM-->        <b><!--CODE-->TO_CHAR</b><!--ENDCODE-->
 +
<!--DEFINITION-->                Sends the message to 'char' and no one else.
 +
<!--TERM-->        <b><!--CODE-->TO_ALL</b><!--ENDCODE-->
 +
<!--DEFINITION-->                Sends the message to everybody in the room.
 +
<!--TERM-->        <b><!--CODE-->TO_REST</b><!--ENDCODE-->
 +
  <!--DEFINITION-->                This is a bit different from the rest.  In sends the message to all other units in the local environment, excluding those inside 'char'.
  
−
=== Hidden Action ===
+
  ---~---~---~---~---~---~---~---~---
−
  dilbegin hidden_action(actor : unitptr);
 
−
code
 
−
{
 
−
    act("$1n vanishes into thin air.", A_HIDEINV, actor, null, null, TO_ROOM);
 
−
    quit;
 
−
} dilend
 
  
−
=== Room-Wide Message ===
+
<span id="formatters"></span>
−
dilbegin announce_to_room(message : string);
+
  '''Act Formatters'''
−
code
 
−
{
 
−
    act(message, A_ALWAYS, self, null, null, TO_ROOM);
 
−
    quit;
 
−
  } dilend
 
  
−
=== Complex Multi-Target Message ===
+
  Just as the description formatters, act has its own set of formatters that
−
  dilbegin complex_message(actor : unitptr, victim : unitptr, weapon : unitptr);
+
  enable you to create generic messages that will be interpreted at run-time,
−
  code
+
  lessening the load on you.
−
{
 
−
    act("$1n attacks $3n with $2n, dealing a deadly blow!", A_ALWAYS, actor, weapon, victim, TO_NOTVICT);
 
−
    act("$3n screams in agony!", A_SOMEONE, actor, null, victim, TO_VICT);
 
−
    quit;
 
−
  } dilend
 
  
−
=== Message with Formatters ===
+
  The format string is a normal message, containing some special characters:
−
  dilbegin formatted_message(actor : unitptr, victim : unitptr);
 
−
code
 
−
{
 
−
    act("$1n smiles at $3n.", A_SOMEONE, actor, null, victim, TO_CHAR);
 
−
    act("$1n smiles at $3n.", A_NOTVICT, actor, null, victim, TO_ROOM);
 
−
    quit;
 
−
} dilend
 
  
−
=== Gender-Aware Messages ===
+
<!--TERM--> '$$'
−
  dilbegin gender_aware_message(actor : unitptr, victim : unitptr);
+
  <!--DEFINITION-->        will be sent to the receiver as a single `$'
−
code
 
−
{
 
−
    act("$1n pats $5n on the head.", A_SOMEONE, actor, null, victim, TO_CHAR);
 
−
    act("$1n pats $5m on the head.", A_SOMEONE, actor, null, victim, TO_ROOM);
 
−
    quit;
 
−
} dilend
 
  
−
=== Conditional Messaging ===
+
  '$', followed by a number and an extra character.
−
  dilbegin conditional_message(actor : unitptr, target : unitptr);
+
  '''The numbers:'''
−
var
 
−
    message : string;
 
−
code
 
−
{
 
−
    if (target != null) {
 
−
      message := "$1n gives $2n to $3n.";
 
−
      act(message, A_SOMEONE, actor, null, target, TO_CHAR);
 
−
      act(message, A_NOTVICT, actor, null, target, TO_ROOM);
 
−
    } else {
 
−
      message := "$1n looks around.";
 
−
      act(message, A_SOMEONE, actor, null, null, TO_ROOM);
 
−
    }
 
−
    quit;
 
−
} dilend
 
  
−
=== Arrest Example ===
+
<!--TERM--> '1'
−
  dilbegin arrest_example(deputy : unitptr, criminal : unitptr, cuffs : unitptr);
+
  <!--DEFINITION-->          means this formatter refers to the 'char' argument.
−
  code
+
  <!--TERM--> '2'
−
  {
+
  <!--DEFINITION-->        means this formatter refers to the 'medium' argument.
−
    act("You cuff $3n.", A_SOMEONE, deputy, null, criminal, TO_CHAR);
+
<!--TERM--> '3'
−
    act("$1n surprises you and puts $2n around your wrists.", A_SOMEONE, deputy, cuffs, criminal, TO_VICT);
+
<!--DEFINITION-->          means this formatter refers to the 'victim' argument.
−
    act("$1n puts $2n around $3N's wrists.", A_SOMEONE, deputy, cuffs, criminal, TO_NOTVICT);
 
−
    quit;
 
−
} dilend
 
  
−
== Error Handling ==
+
    '''The characters'''
−
The function performs validation:
 
−
* '''Message validation'' - Ensures message parameter is a string
 
−
* '''Type validation'' - Ensures visibility, char, medium, victim are appropriate types
 
−
* '''Unit validation'' - Ensures char, medium, and victim are valid unit pointers
 
−
* '''Target validation'' - Ensures victim is valid when using TO_VICT flag
 
  
−
Note: The C implementation shows that this function:
+
<!--TERM--> 'N'
−
* Supports multiple parameter combinations (from 2 to 6 parameters)
+
<!--DEFINITION-->          the formatter will be replaced with the name of the unit, or (depending on the visibility) 'something' or 'someone'.
−
* Uses formatters for dynamic message content
+
<!--TERM--> 'a'
−
* Handles gender-aware name substitution
+
<!--DEFINITION-->        'a' or 'an' depending on the name of the unit referred by the number.
−
* Performs complex visibility calculations based on flags
+
<!--TERM--> 'e'
−
* Returns DILV_SP (string) for the generated message
+
<!--DEFINITION-->        'it', 'he' or 'she' depending on the gender of the unit referred by the number.
 +
<!--TERM--> 'm'
 +
<!--DEFINITION-->        'it', 'him' or 'her' depending on the gender of the unit referred by the number.
 +
<!--TERM--> 'n'
 +
<!--DEFINITION-->          the formatter will be replaced with the title of the unit, or (depending on the visibility) 'something' or 'someone'.
 +
<!--TERM--> 'p'
 +
<!--DEFINITION-->        'fighting', 'standing', 'sleeping', etc., depending on the positionof the unit referred by the number.
 +
<!--TERM--> 's'
 +
<!--DEFINITION-->        'its', 'his' or 'her' depending on the gender of the unit referred by the number.
 +
<!--TERM--> 't'
 +
<!--DEFINITION-->        the string in the argument referred by the number.
  
−
== Usage Notes ==
 
−
* This function is the primary method for sending messages to players
 
−
* The message parameter supports formatters for dynamic content
 
−
* Visibility flags control who sees the message
 
−
* The function is commonly used for combat, social interactions, and environmental descriptions
 
−
* Gender-aware formatters ($5, $6, etc.) automatically adapt to victim's gender
 
−
* The function is more efficient than multiple send() calls for complex messages
 
−
* Use appropriate visibility flags to control message flow and prevent spam
 
−
* The char parameter is required for most visibility modes except TO_ROOM and TO_ALL
 
  
−
== Related Functions ==
 
−
* [[send]] - Send message to specific character
 
−
* [[sendtext]] - Send text to character without formatting
 
−
* [[sendto]] - Send message to specific unit
 
−
* [[sendtoall]] - Send message to all units in local environment
 
  
−
== See Also ==
+
'''Example:'''
−
* [[unitptr]] - Unit pointer data type
+
 
−
* [[visibility]] - Unit visibility field
+
<nowiki>
−
* [[position]] - Character position field
+
 
−
* [[A_*]] - Action visibility constants
+
  act("You step over $2n.", A_SOMEONE, self, litter, null, TO_CHAR);
 +
  act("$1n steps over $2n.", A_SOMEONE, self, litter, null, TO_REST);</nowiki>
 +
 
 +
 
 +
'''See Also:'''
 +
  [[#act.html|DIL Act() for Dummies]]
 +
 
 +
---~---~---~---~---~---~---~---~---

Latest revision as of 10:44, 4 December 2025


The purpose of act is to send a message to a number of players present in
a room.  The room is defined as the room containing the afore mentioned
character (provided he himself is in the room, i.e. not in a closed
container.)



---~---~---~---~---~---~---~---~---

Syntax:

act(message, visibility, char, medium, victim, to_whom);



 message
          - is a string that will be shown to other mobiles when the act is executed. To refer to the following arguments use the formatters listed below.
 visibility
          - is an integer that defines what happens if the mobile that is about to receive the message can't see the activator.
         A_SOMEONE
                If the receiver cannot see char, replace any reference to char with someone.
         A_HIDEINV
                If the receiver cannot see char, don't send the message at all.	Use this when missing vision should eliminate the perception of the action the message represent. One instance where it is used is in smile. You would need a ridiculously sensitive ear to hear, let alone percept that someone's smiling if you can't see them. Do not use it if 'sound' is inherent in the message.
         A_ALWAYS
                Works exactly like A_SOMEONE, except that the receiver will see the message even when sleeping.
 char
          - is a unitptr, and the most important argument in the act. If this is not valid the act will never show, leaving mobiles without the message.
 medium
          - is a unit pointer, an integer or a string. Use this at your leisure.
 victim
          - is a unit pointer, an integer or a string. Certain flags in the next argument rely on the validity of victim.
 to_whom
          - is an integer that defines who gets the message.
         TO_ROOM
                Sends the message to the entire room, excluding 'char'.
         TO_VICT
                Sends to 'victim' only. 'victim' must be valid, naturally.
         TO_NOTVICT
                Sends the message to the entire room, excluding 'char' and 'victim'.  Perfect for bystanders in a melee.
         TO_CHAR
                Sends the message to 'char' and no one else.
         TO_ALL
                Sends the message to everybody in the room.
         TO_REST
                This is a bit different from the rest.  In sends the message to all other units in the local environment, excluding those inside 'char'.

---~---~---~---~---~---~---~---~---


Act Formatters

Just as the description formatters, act has its own set of formatters that
enable you to create generic messages that will be interpreted at run-time,
lessening the load on you.

The format string is a normal message, containing some special characters:

 '$$'
         will be sent to the receiver as a single `$'

'$', followed by a number and an extra character.
  The numbers:

 '1'
          means this formatter refers to the 'char' argument.
 '2'
         means this formatter refers to the 'medium' argument.
 '3'
          means this formatter refers to the 'victim' argument.

   The characters

 'N'
          the formatter will be replaced with the name of the unit, or (depending on the visibility) 'something' or 'someone'.
 'a'
         'a' or 'an' depending on the name of the unit referred by the number.
 'e'
         'it', 'he' or 'she' depending on the gender of the unit referred by the number.
 'm'
         'it', 'him' or 'her' depending on the gender of the unit referred by the number.
 'n'
          the formatter will be replaced with the title of the unit, or (depending on the visibility) 'something' or 'someone'.
 'p'
         'fighting', 'standing', 'sleeping', etc., depending on the positionof the unit referred by the number.
 's'
         'its', 'his' or 'her' depending on the gender of the unit referred by the number.
 't'
         the string in the argument referred by the number.



Example:


   act("You step over $2n.", A_SOMEONE, self, litter, null, TO_CHAR);
   act("$1n steps over $2n.", A_SOMEONE, self, litter, null, TO_REST);



See Also:
  DIL Act() for Dummies

---~---~---~---~---~---~---~---~---
Retrieved from "http://wiki.dikumud.net/index.php?title=Manual:DIL_Manual/act()&oldid=1062"