### Multiple Fallback Decorators Example

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Shows an example with multiple fallback decorators, where the application checks them in sequence until a recognized decorator is found.

```text
@@risu_only_decorator 4
@@@agn_only_decorator 4
@@@activate_every 4
```

--------------------------------

### Decorator Fallback Syntax Example

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Demonstrates how to implement fallback decorators using '@@@'. If the primary decorator is not recognized, the application attempts to use the fallback decorator.

```text
@@risu_only_decorator 4
@@@activate_after 4
@@depth 5
@@@instruct_depth 5
```

--------------------------------

### Decorator Syntax Example

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Illustrates the basic syntax for using decorators, including decorators with string values, numeric values, boolean values, multiple values, and decorators without values.

```text
@@decorator_with_string_value value
@@another_decorator_with_string_value value
@@decorator_with_number_value 4
@@decorator_with_boolean_value true
@@decorator_with_multiple_values value1,value2,value3
@@decorator_without_value

Some lorebook content
```

--------------------------------

### Example Lorebook Entry with Decorators

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/concepts.md

Demonstrates how to use decorators like @@depth and @@ignore_on_max_context to control lorebook entry behavior and positioning. These decorators allow for advanced prompt manipulation without requiring new fields.

```plaintext
@@depth 5
@@ignore_on_max_context

Prompt text here
```

--------------------------------

### Curly Braced Syntaxes (CBS) Examples

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Demonstrates the usage of various curly braced syntaxes (CBS) or macros within strings, showing how they are intended to be replaced with dynamic values. This is common in templating or prompt engineering.

```plaintext
# {{char}} example:
# Replaced with the character's nickname or name.
"Hello, I am {{char}}."

# {{user}} example:
# Replaced with the user's display name.
"How can I help you today, {{user}}?"

# {{random:A,B,C...}} example:
# Replaced with one of the provided options randomly.
"My greeting is {{random:Hello,Hi,Hey}}."

# {{pick:A,B,C...}} example:
# Similar to random, but aims for consistency per prompt.
"Choose wisely: {{pick:Option1,Option2,Option3}}."

# {{roll:N}} example:
# Replaced with a random number between 1 and N.
"You rolled a {{roll:6}}."

# {{// A}} example:
# This part is a comment and should not appear in the final prompt.
"This is a message {{// This is a hidden comment}}."

# {{hidden_key:A}} example:
# Similar to //, but can be used in lorebook matching.
"{{hidden_key:important_keyword}}"

# {{comment: A}} example:
# Replaced with empty string for prompts, shown as inline comment in messages.
"{{comment: This is an inline comment}}"

# {{reverse:A}} example:
# Replaced with the reversed string.
"The reverse of 'world' is {{reverse:world}}. "

```

--------------------------------

### Decorator Examples in Python

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Illustrates how decorators like @@exclude_keys and @@is_user_icon might be implemented or interpreted in a Python context. These decorators modify the behavior of matching logic for lorebook entries based on specific conditions.

```python
class CharacterCardV3:
    def __init__(self):
        self.lorebook_entries = []

    def add_lorebook_entry(self, entry):
        self.lorebook_entries.append(entry)

# Example of how decorators might influence matching logic (conceptual)
# In a real implementation, this would be part of the matching engine.

# @@exclude_keys decorator example
# If the user's message contains 'key1' or 'key2', this lorebook entry is ignored.
# lorebook_entry_exclude = {
#     'text': 'Some lore',
#     'decorators': {'exclude_keys': ['key1', 'key2']}
# }

# @@is_user_icon decorator example
# If the active user icon's name is not 'icon_name', this entry is ignored.
# lorebook_entry_user_icon = {
#     'text': 'Another lore',
#     'decorators': {'is_user_icon': 'icon_name'}
# }

# @@dont_activate and @@activate decorators example
# This entry is only considered if @@activate is present.
# lorebook_entry_activate = {
#     'text': 'Conditional lore',
#     'decorators': {'dont_activate': True, 'activate': True}
# }

# @@disable_ui_prompt decorator example
# May disable the 'system_prompt' UI element.
# lorebook_entry_disable_ui = {
#     'text': 'UI hint',
#     'decorators': {'disable_ui_prompt': 'system_prompt'}
# }

```

--------------------------------

### Control Lorebook Entry Activation with Decorators

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/concepts.md

These decorators control the activation and visibility of lorebook entries based on specific conditions or absolute rules. They are essential for managing bot behavior and content.

```text
@@exclude_keys N,N...
@@is_user_icon N
@@dont_activate
@@activate
@@disable_ui_prompt
```

--------------------------------

### Lorebook Entry with Fallback Decorators

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/concepts.md

Illustrates the use of fallback decorators (@@@) for handling unsupported decorators. If a primary decorator is not supported by the application, it falls back to a secondary or tertiary option, ensuring broader compatibility.

```plaintext
@@activate_after_emotion
@@@instruct_depth 100
@@@depth 5

Prompt text here
```

--------------------------------

### Handle CCv2 backfill in PNG/APNG

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Applications may backfill Character Card V2 objects from 'chara' chunks in PNG/APNG files. A warning should be added to the 'creator_notes' field in the TavernCardV2 object indicating it's backfilled from CCv3. The backfilled 'chara' chunk should ideally be trimmed on import.

```text
Warning message example: "This character card is Character Card V3, but it is loaded as a Character Card V2. Please use a Character Card V3 compatible application to use this character card properly."
```

--------------------------------

### Dynamic Content with Curly Braced Syntax (CBS)

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/concepts.md

Curly Braced Syntax (CBS) provides a standardized way to include dynamic elements within character cards. This includes random selection, deterministic selection, dice rolling, comments, and string manipulation.

```text
{{random:A,B,C...}}
{{pick:A,B,C...}}
{{roll:N}}
{{// A}}
{{/// A}}
{{comment:A}}
{{reverse:A}}
```

--------------------------------

### Embed Assets in PNG/APNG using tEXt chunks

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Additional tEXt chunks can be used to embed assets in PNG/APNG files, mimicking CHARX files. These chunks must be named 'chara-ext-asset_:{path}' and their values should be base64 encoded binary data. Access is via '__asset:{path}' URI. However, implementing this is discouraged for new applications; CHARX files are preferred.

```text
tEXt chunk name: chara-ext-asset_:{path}
tEXt chunk value: base64(binary data)
Access URI: __asset:{path}
```

--------------------------------

### Lorebook TypeScript Interface Definition

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Defines the structure of the Lorebook object, including its properties like name, description, scan_depth, token_budget, recursive_scanning, extensions, and entries. Each entry within the entries array has its own set of properties such as keys, content, extensions, enabled status, and various optional fields.

```typescript
type Lorebook = {
  name?: string
  description?: string
  scan_depth?: number 
  token_budget?: number
  recursive_scanning?: boolean
  extensions: Record<string, any>
  entries: Array<{
    keys: Array<string>
    content: string
    extensions: Record<string, any>
    enabled: boolean
    insertion_order: number
    case_sensitive?: boolean

    //V3 Additions
    use_regex: boolean

    //On V2 it was optional, but on V3 it is required to implement
    constant?: boolean

    // Optional Fields
    name?: string
    priority?: number
    id?: number|string
    comment?: string

    selective?: boolean
    secondary_keys?: Array<string>
    position?: 'before_char' | 'after_char'
  }>
}
```

--------------------------------

### Lorebook Export/Import Structure

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Defines the JSON structure for exporting and importing a Lorebook alone. It includes a 'spec' field to identify the version and a 'data' field containing the Lorebook object itself. Applications should handle unknown fields gracefully during import.

```typescript
{
  spec: 'lorebook_v3',
  data: Lorebook
}
```

--------------------------------

### Default Asset Structure in TypeScript

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

This snippet illustrates the default structure for an asset when the 'assets' field is undefined. It specifies the required fields and their types for an asset object.

```typescript
[
  {
    type: 'icon',
    uri: 'ccdefault:',
    name: 'main',
    ext: 'png'
  }
]
```

--------------------------------

### Prioritize CCv3 over CCv2 chunks in PNG/APNG

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

If both 'chara' and 'ccv3' chunks are detected in a PNG/APNG file, applications should prioritize and use the 'ccv3' chunk.

```text
If 'chara' and 'ccv3' exist, use 'ccv3'.
```

--------------------------------

### CharacterCardV3 TypeScript Interface

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

Defines the structure of the CharacterCardV3 object, including fields from V2 and new/modified fields in V3. This interface serves as a blueprint for the JSON object.

```typescript
interface CharacterCardV3{
  spec: 'chara_card_v3'
  spec_version: '3.0'
  data: {
    // fields from CCV2
    name: string
    description: string
    tags: Array<string>
    creator: string
    character_version: string
    mes_example: string
    extensions: Record<string, any>
    system_prompt: string
    post_history_instructions: string
    first_mes: string
    alternate_greetings: Array<string>
    personality: string
    scenario: string

    //Changes from CCV2
    creator_notes: string
    character_book?: Lorebook

    //New fields in CCV3
    assets?: Array<{
      type: string
      uri: string
      name: string
      ext: string
    }>
    nickname?: string
    creator_notes_multilingual?: Record<string, string>
    source?: string[]
    group_only_greetings: Array<string>
    creation_date?: number
    modification_date?: number
  }
}
```

--------------------------------

### Embed CCv3 in PNG/APNG using tEXt chunk

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

CharacterCardV3 objects must be embedded in PNG or APNG files within a tEXt chunk. This chunk must be named 'ccv3' and its value should be the base64 encoded JSON string of the CharacterCardV3 object (UTF-8 encoded).

```text
tEXt chunk name: ccv3
tEXt chunk value: base64(utf-8(CharacterCardV3 JSON string))
```

--------------------------------

### Embed CCv3 in JSON file

Source: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md

CharacterCardV3 objects can be embedded directly within JSON files. The JSON file itself must be a valid CharacterCardV3 object.

```json
{
  "title": "Example Character Card",
  "description": "A sample CCv3 object embedded in a JSON file.",
  "version": 3,
  "data": { ... }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.