generate_random_event

Instructions

Trigger a series of events based on given probabilities, each event has an independent trigger probability.
Uses bitmap to record trigger status for easy processing.

Args:
    event_count (int): Total number of events
    event_probabilities (List[int]): Trigger probability for each event (0-1000, representing 0-100%)
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing event trigger results, formatted as:
    {
        "requestId": "Generated request ID",
        "triggeredEvents": Event trigger bitmap,
        "eventResults": [
            {
                "eventId": Event ID,
                "probability": Trigger probability,
                "triggered": Whether triggered,
                "randomValue": Random value
            },
            ...
        ]
    }

Application Scenarios:
1. Game random events (trigger plot, drop items)
2. Probability effect determination (skill trigger, combo determination)
3. Risk event simulation (fault prediction, accident events)
4. Multiple condition determination (combined probability events)

Implementation Reference

• main.py:177-211 (handler)

  MCP tool handler for 'generate_random_event' decorated with @mcp.tool(). Delegates to utils.random_event_trigger for core logic.

  @mcp.tool()
  async def generate_random_event(event_count: int, event_probabilities: List[int], salt: str = "") -> str:
      """Random Event Trigger
  
      Trigger a series of events based on given probabilities, each event has an independent trigger probability.
      Uses bitmap to record trigger status for easy processing.
  
      Args:
          event_count (int): Total number of events
          event_probabilities (List[int]): Trigger probability for each event (0-1000, representing 0-100%)
          salt (str, optional): Random number salt value for increased randomness. Defaults to "".
  
      Returns:
          str: JSON string containing event trigger results, formatted as:
          {
              "requestId": "Generated request ID",
              "triggeredEvents": Event trigger bitmap,
              "eventResults": [
                  {
                      "eventId": Event ID,
                      "probability": Trigger probability,
                      "triggered": Whether triggered,
                      "randomValue": Random value
                  },
                  ...
              ]
          }
  
      Application Scenarios:
      1. Game random events (trigger plot, drop items)
      2. Probability effect determination (skill trigger, combo determination)
      3. Risk event simulation (fault prediction, accident events)
      4. Multiple condition determination (combined probability events)
      """
      return await random_event_trigger(event_count, event_probabilities, salt)

• utils.py:411-463 (helper)

  Core helper function implementing the random event triggering logic using blockchain-derived randomness, numpy seeding, probability checks, and bitmap encoding.

  async def random_event_trigger(event_count: int, event_probabilities: List[int], salt: str="") -> Dict:
      """
      Random event trigger
      
      Trigger events based on their individual probabilities
      
      Args:
          event_count: Number of events
          event_probabilities: Probability for each event (0-1000)
          salt: Optional salt value for additional randomness
          
      Returns:
          Dict containing triggered events and their results
      """
      if len(event_probabilities) != event_count:
          raise ValueError("Event count must match probabilities array length")
      random_num = await get_random_str()
      if not random_num:
          return {"error": "Failed to get random number"}
      request_id = generate_request_id(random_num)
      seed = _derive_seed(request_id, salt)
      np.random.seed(seed)
      
      triggered_events = 0
      event_results = []
      
      for i in range(event_count):
          probability = event_probabilities[i]
          if not 0 <= probability <= 1000:
              raise ValueError("Probability must be between 0 and 1000")
          
          # Generate random number between 0-999
          random_value = np.random.randint(0, 1000)
          is_triggered = random_value < probability
          
          event_results.append({
              "eventId": i,
              "probability": probability / 10,  # Convert to percentage
              "triggered": is_triggered,
              "randomValue": int(random_value)
          })
          
          # Encode trigger result into bitmap
          if is_triggered:
              triggered_events |= (1 << i)
      
      result = {
          "requestId": request_id,
          "triggeredEvents": triggered_events,
          "eventResults": event_results
      }
      
      return result