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

From DikuMUD Wiki
Jump to navigation Jump to search
Line 1: Line 1:
−
= act() =
+
= act =
  
−
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 aforementioned character (provided he himself is in the room, i.e. not in a closed container.)
+
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: ==
+
== Syntax ==
 +
act(string message, integer visibility, unitptr char, unitptr medium, unitptr victim, integer to_whom)
  
−
  act(message, visibility, char, medium, victim, to_whom);
+
== Parameters ==
 +
{| class="wikitable"
 +
! Parameter !! Type !! Description
 +
|-
 +
| 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)
 +
|}
  
−
== Parameters: ==
+
== Return Value ==
−
'''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|formatters]] listed below.
+
This function does not return a value (void).
  
−
'''visibility:''' is an integer that defines what happens if the mobile that is about to receive the message can't see the activator.
+
== Visibility Flags ==
−
* A_SOMEONE
+
{| class="wikitable"
−
If the receiver cannot see char, replace any reference to char with <i>someone</i>.
+
! Flag !! Value !! Description
−
* 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_SOMEONE || Send to character only
−
* A_ALWAYS
+
|-
−
Works exactly like A_SOMEONE, except that the receiver will see the message even when sleeping.
+
| 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
 +
|}
  
−
'''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.
+
== Message Formatters ==
 +
The message string can contain special formatters that are replaced at runtime:
  
−
'''medium:''' is a unit pointer, an integer or a string. Use this at your leisure.
+
{| class="wikitable"
 +
! 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)
 +
|}
  
−
'''victim''' is a unit pointer, an integer or a string. Certain flags in the next argument rely on the validity of victim.
+
== 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
  
−
'''to_whom''' is an integer that defines who gets the message.
+
=== Combat Message ===
 +
dilbegin combat_message(attacker : unitptr, defender : unitptr);
 +
code
 +
{
 +
    act("$1n attacks $3n with deadly force!", A_ALWAYS, attacker, null, defender, TO_VICT);
 +
    act("$1n attacks $3n with deadly force!", A_NOTVICT, attacker, null, defender, TO_ROOM);
 +
    quit;
 +
} dilend
  
−
* TO_ROOM
+
=== Hidden Action ===
−
Sends the message to the entire room, excluding 'char'.
+
  dilbegin hidden_action(actor : unitptr);
−
* TO_VICT
+
  code
−
<!--DEFINITION-->                Sends to 'victim' only. 'victim' must be valid, naturally.
+
  {
−
  <!--TERM-->        <b><!--CODE-->TO_NOTVICT</b><!--ENDCODE-->
+
    act("$1n vanishes into thin air.", A_HIDEINV, actor, null, null, TO_ROOM);
−
  <!--DEFINITION-->                Sends the message to the entire room, excluding 'char' and 'victim'.  Perfect for bystanders in a melee.
+
    quit;
−
  <!--TERM-->        <b><!--CODE-->TO_CHAR</b><!--ENDCODE-->
+
  } dilend
−
<!--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'.
 
  
−
  ---~---~---~---~---~---~---~---~---
+
=== Room-Wide Message ===
 +
dilbegin announce_to_room(message : string);
 +
code
 +
{
 +
    act(message, A_ALWAYS, self, null, null, TO_ROOM);
 +
    quit;
 +
  } dilend
  
−
  <span id="formatters"></span>
+
=== Complex Multi-Target Message ===
−
  '''Act Formatters'''
+
dilbegin complex_message(actor : unitptr, victim : unitptr, weapon : unitptr);
 +
  code
 +
{
 +
    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
  
−
  Just as the description formatters, act has its own set of formatters that
+
=== Message with Formatters ===
−
enable you to create generic messages that will be interpreted at run-time,
+
  dilbegin formatted_message(actor : unitptr, victim : unitptr);
−
  lessening the load on you.
+
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
  
−
  The format string is a normal message, containing some special characters:
+
=== Gender-Aware Messages ===
 +
  dilbegin gender_aware_message(actor : unitptr, victim : unitptr);
 +
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
  
−
  <!--TERM--> '$$'
+
=== Conditional Messaging ===
−
  <!--DEFINITION-->        will be sent to the receiver as a single `$'
+
dilbegin conditional_message(actor : unitptr, target : unitptr);
 +
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
  
−
  '$', followed by a number and an extra character.
+
=== Arrest Example ===
−
  '''The numbers:'''
+
  dilbegin arrest_example(deputy : unitptr, criminal : unitptr, cuffs : unitptr);
 +
code
 +
{
 +
    act("You cuff $3n.", A_SOMEONE, deputy, null, criminal, TO_CHAR);
 +
    act("$1n surprises you and puts $2n around your wrists.", A_SOMEONE, deputy, cuffs, criminal, TO_VICT);
 +
    act("$1n puts $2n around $3N's wrists.", A_SOMEONE, deputy, cuffs, criminal, TO_NOTVICT);
 +
    quit;
 +
} dilend
  
−
<!--TERM--> '1'
+
== Error Handling ==
−
<!--DEFINITION-->          means this formatter refers to the 'char' argument.
+
The function performs validation:
−
<!--TERM--> '2'
+
* '''Message validation'' - Ensures message parameter is a string
−
<!--DEFINITION-->        means this formatter refers to the 'medium' argument.
+
* '''Type validation'' - Ensures visibility, char, medium, victim are appropriate types
−
<!--TERM--> '3'
+
* '''Unit validation'' - Ensures char, medium, and victim are valid unit pointers
−
<!--DEFINITION-->          means this formatter refers to the 'victim' argument.
+
* '''Target validation'' - Ensures victim is valid when using TO_VICT flag
  
−
    '''The characters'''
+
Note: The C implementation shows that this function:
 +
* Supports multiple parameter combinations (from 2 to 6 parameters)
 +
* Uses formatters for dynamic message content
 +
* Handles gender-aware name substitution
 +
* Performs complex visibility calculations based on flags
 +
* Returns DILV_SP (string) for the generated message
  
−
<!--TERM--> 'N'
+
== Usage Notes ==
−
<!--DEFINITION-->          the formatter will be replaced with the name of the unit, or (depending on the visibility) 'something' or 'someone'.
+
* This function is the primary method for sending messages to players
−
<!--TERM--> 'a'
+
* The message parameter supports formatters for dynamic content
−
<!--DEFINITION-->        'a' or 'an' depending on the name of the unit referred by the number.
+
* Visibility flags control who sees the message
−
<!--TERM--> 'e'
+
* The function is commonly used for combat, social interactions, and environmental descriptions
−
<!--DEFINITION-->        'it', 'he' or 'she' depending on the gender of the unit referred by the number.
+
* Gender-aware formatters ($5, $6, etc.) automatically adapt to victim's gender
−
<!--TERM--> 'm'
+
* The function is more efficient than multiple send() calls for complex messages
−
<!--DEFINITION-->        'it', 'him' or 'her' depending on the gender of the unit referred by the number.
+
* Use appropriate visibility flags to control message flow and prevent spam
−
<!--TERM--> 'n'
+
* The char parameter is required for most visibility modes except TO_ROOM and TO_ALL
−
<!--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.
 
  
 +
== 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]]
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 

Revision as of 21:15, 29 November 2025

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

act(string message, integer visibility, unitptr char, unitptr medium, unitptr victim, integer to_whom)

Parameters

Parameter Type Description
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

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

The message string can contain special formatters that are replaced at runtime:

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

dilbegin combat_message(attacker : unitptr, defender : unitptr);
code
{
   act("$1n attacks $3n with deadly force!", A_ALWAYS, attacker, null, defender, TO_VICT);
   act("$1n attacks $3n with deadly force!", A_NOTVICT, attacker, null, defender, TO_ROOM);
   quit;
} dilend

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

dilbegin announce_to_room(message : string);
code
{
   act(message, A_ALWAYS, self, null, null, TO_ROOM);
   quit;
} dilend

Complex Multi-Target Message

dilbegin complex_message(actor : unitptr, victim : unitptr, weapon : unitptr);
code
{
   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

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

dilbegin gender_aware_message(actor : unitptr, victim : unitptr);
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

dilbegin conditional_message(actor : unitptr, target : unitptr);
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

dilbegin arrest_example(deputy : unitptr, criminal : unitptr, cuffs : unitptr);
code
{
   act("You cuff $3n.", A_SOMEONE, deputy, null, criminal, TO_CHAR);
   act("$1n surprises you and puts $2n around your wrists.", A_SOMEONE, deputy, cuffs, criminal, TO_VICT);
   act("$1n puts $2n around $3N's wrists.", A_SOMEONE, deputy, cuffs, criminal, TO_NOTVICT);
   quit;
} dilend

Error Handling

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:

  • Supports multiple parameter combinations (from 2 to 6 parameters)
  • Uses formatters for dynamic message content
  • Handles gender-aware name substitution
  • Performs complex visibility calculations based on flags
  • Returns DILV_SP (string) for the generated message

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

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