dfpyre 0.4.6__py3-none-any.whl → 0.8.1__py3-none-any.whl

dfpyre/pyre.py

@@ -1,40 +1,27 @@
 """
-A package for externally creating code templates for the DiamondFire Minecraft server.
+A package for making code templates for the DiamondFire Minecraft server.
 
 By Amp
-2/24/2024
 """
 
-import base64
-import gzip
-import socket
-import websocket
-import time
 import json
-import os
 from difflib import get_close_matches
 import datetime
-from typing import Tuple, List, Dict
 from enum import Enum
 from mcitemlib.itemlib import Item as NbtItem
+from dfpyre.util import *
 from dfpyre.items import *
+from dfpyre.scriptgen import generate_script, GeneratorFlags
+from dfpyre.actiondump import CODEBLOCK_DATA, get_default_tags
 
-COL_WARN = '\x1b[33m'
-COL_RESET = '\x1b[0m'
-COL_SUCCESS = '\x1b[32m'
-COL_ERROR = '\x1b[31m'
-
-CODEBLOCK_DATA_PATH = os.path.join(os.path.dirname(__file__), 'data/data.json')
 
 VARIABLE_TYPES = {'txt', 'comp', 'num', 'item', 'loc', 'var', 'snd', 'part', 'pot', 'g_val', 'vec', 'pn_el'}
 TEMPLATE_STARTERS = {'event', 'entity_event', 'func', 'process'}
+DYNAMIC_CODEBLOCKS = {'func', 'process', 'call_func', 'start_process'}
 
 TARGETS = ['Selection', 'Default', 'Killer', 'Damager', 'Shooter', 'Victim', 'AllPlayers', 'Projectile', 'AllEntities', 'AllMobs', 'LastEntity']
 TARGET_CODEBLOCKS = {'player_action', 'entity_action', 'if_player', 'if_entity'}
 
-VAR_SHORTHAND_CHAR = '$'
-VAR_SCOPES = {'g': 'unsaved', 's': 'saved', 'l': 'local', 'i': 'line'}
-
 CODECLIENT_URL = 'ws://localhost:31375'
 
 
@@ -51,153 +38,171 @@ class Target(Enum):
     ALL_MOBS = 9
     LAST_ENTITY = 10
 
-    def getStringValue(self):
+    def get_string_value(self):
         return TARGETS[self.value]
 
 DEFAULT_TARGET = Target.SELECTION
 
 
+def _convert_args(args):
+    return tuple(map(convert_argument, args))
+
+
 class CodeBlock:
-    def __init__(self, name: str, args: Tuple=(), target: Target=DEFAULT_TARGET, data: Dict={}):
-        self.name = name
+    def __init__(self, codeblock_type: str, action_name: str, args: tuple=(), target: Target=DEFAULT_TARGET, data: dict={}, tags: dict[str, str]={}):
+        self.type = codeblock_type
+        self.action_name = action_name
         self.args = args
         self.target = target
         self.data = data
+        self.tags = tags
+    
 
-
-def _warn(message):
-    print(f'{COL_WARN}! WARNING ! {message}{COL_RESET}')
-
-
-def _warnUnrecognizedName(codeblockType: str, codeblockName: str):
-    close = get_close_matches(codeblockName, TAGDATA[codeblockType].keys())
+    @classmethod
+    def new_action(cls, codeblock_type: str, action_name: str, args: tuple, tags: dict[str, str], target: Target=DEFAULT_TARGET) -> "CodeBlock":
+        args = _convert_args(args)
+        return cls(codeblock_type, action_name, args=args, data={'id': 'block', 'block': codeblock_type, 'action': action_name}, tags=tags, target=target)
+
+    @classmethod
+    def new_data(cls, codeblock_type: str, data_value: str, args: tuple, tags: dict[str, str]) -> "CodeBlock":
+        args = _convert_args(args)
+        return cls(codeblock_type, 'dynamic', args=args, data={'id': 'block', 'block': codeblock_type, 'data': data_value}, tags=tags)
+
+    @classmethod
+    def new_conditional(cls, codeblock_type: str, action_name: str, args: tuple, tags: dict[str, str], inverted: bool, target: Target=DEFAULT_TARGET) -> "CodeBlock":
+        args = _convert_args(args)
+        data = {'id': 'block', 'block': codeblock_type, 'action': action_name}
+        if inverted:
+            data['attribute'] = 'NOT'
+        return cls(codeblock_type, action_name, args=args, data=data, tags=tags, target=target)
+
+    @classmethod
+    def new_repeat(cls, action_name: str, args: tuple, tags: dict[str, str], sub_action: str|None, inverted: bool) -> "CodeBlock":
+        args = _convert_args(args)
+        data = {'id': 'block', 'block': 'repeat', 'action': action_name}
+        if inverted:
+            data['attribute'] = 'NOT'
+        if sub_action is not None:
+            data['subAction'] = sub_action
+        return cls('repeat', action_name, args=args, data=data, tags=tags)
+
+    @classmethod
+    def new_else(cls) -> "CodeBlock":
+        return cls('else', 'else', data={'id': 'block', 'block': 'else'})
+
+    @classmethod
+    def new_bracket(cls, direction: Literal['open', 'close'], bracket_type: Literal['norm', 'repeat']) -> "CodeBlock":
+        return cls('bracket', 'bracket', data={'id': 'bracket', 'direct': direction, 'type': bracket_type})
+
+
+    def __repr__(self) -> str:
+        if self.action_name == 'dynamic':
+            return f'CodeBlock({self.data["block"]}, {self.data["data"]})'
+        if self.action_name == 'else':
+            return 'CodeBlock(else)'
+        if 'block' in self.data:
+            return f'CodeBlock({self.data["block"]}, {self.action_name})'
+        return f'CodeBlock(bracket, {self.data["type"]}, {self.data["direct"]})'
+
+
+    def build(self, include_tags: bool=True) -> dict:
+        """
+        Builds a properly formatted block from a CodeBlock object.
+        """
+        built_block = self.data.copy()
+        
+        # add target if necessary ('Selection' is the default when 'target' is blank)
+        if self.type in TARGET_CODEBLOCKS and self.target != DEFAULT_TARGET:
+            built_block['target'] = self.target.get_string_value()
+        
+        # add items into args
+        final_args = [arg.format(slot) for slot, arg in enumerate(self.args) if arg.type in VARIABLE_TYPES]
+        
+        # check for unrecognized name, add tags
+        if self.type not in {'bracket', 'else'}:
+            if self.action_name not in CODEBLOCK_DATA[self.type]:
+                _warn_unrecognized_name(self.type, self.action_name)
+            elif include_tags:
+                tags = _get_codeblock_tags(self.type, self.action_name, self.tags)
+                if len(final_args) + len(tags) > 27:
+                    final_args = final_args[:(27-len(tags))]  # trim list if over 27 elements
+                final_args.extend(tags)  # add tags to end
+
+        built_block['args'] = {'items': final_args}
+        return built_block
+
+
+def _warn_unrecognized_name(codeblock_type: str, codeblock_name: str):
+    close = get_close_matches(codeblock_name, CODEBLOCK_DATA[codeblock_type].keys())
     if close:
-        _warn(f'Code block name "{codeblockName}" not recognized. Did you mean "{close[0]}"?')
+        warn(f'Code block name "{codeblock_name}" not recognized. Did you mean "{close[0]}"?')
     else:
-        _warn(f'Code block name "{codeblockName}" not recognized. Try spell checking or retyping without spaces.')
+        warn(f'Code block name "{codeblock_name}" not recognized. Try spell checking or retyping without spaces.')
 
 
-def _loadCodeblockData() -> Tuple:
-    tagData = {}
-    if os.path.exists(CODEBLOCK_DATA_PATH):
-        with open(CODEBLOCK_DATA_PATH, 'r') as f:
-            tagData = json.load(f)
-    else:
-        _warn('data.json not found -- Item tags and error checking will not work.')
-        return ({}, set(), set())
+def _check_applied_tags(tags: list[dict], applied_tags: dict[str, str], codeblock_name: str) -> dict[str, str]:
+    if len(applied_tags) > 0 and len(tags) == 0:
+        warn(f'Action "{codeblock_name}" does not have any tags, but still received {len(applied_tags)}.')
+        return {}
     
-    del tagData['meta']
-
-    allNames = [x for l in [d.keys() for d in tagData.values()] for x in l]  # flatten list
-    return (
-        tagData,
-        set(tagData['extras'].keys()),
-        set(allNames)
-    )
-
-TAGDATA, TAGDATA_EXTRAS_KEYS, ALL_CODEBLOCK_NAMES = _loadCodeblockData()
-
-def _addInverted(data, inverted):
-    """
-    If inverted is true, add 'inverted': 'NOT' to data.
-    """
-    if inverted:
-        data['inverted'] = 'NOT'
-
-
-def _convertDataTypes(args):
-    convertedArgs = []
-    for value in args:
-        if type(value) in {int, float}:
-            convertedArgs.append(num(value))
-        elif type(value) is str:
-            if value[0] == VAR_SHORTHAND_CHAR and value[1] in VAR_SCOPES:
-                varObject = var(value[2:], VAR_SCOPES[value[1]])
-                convertedArgs.append(varObject)
-            else:
-                convertedArgs.append(text(value))
+    valid_tags = {}
+    tags_formatted = {t['name']: t for t in tags}
+    for name, option in applied_tags.items():
+        if name not in tags_formatted:
+            tag_names_joined = '\n'.join(map(lambda s: '    - '+s, tags_formatted.keys()))
+            warn(f'Tag "{name}" does not exist for action "{codeblock_name}". Available tags:\n{tag_names_joined}')
+        elif option not in tags_formatted[name]['options']:
+            options_joined = '\n'.join(map(lambda s: '    - '+s, tags_formatted[name]['options']))
+            warn(f'Tag "{name}" does not have the option "{option}". Available tag options:\n{options_joined}')
         else:
-            convertedArgs.append(value)
-    return tuple(convertedArgs)
+            valid_tags[name] = option
+    return valid_tags
 
 
-def _reformatCodeblockTags(tags, codeblockType: str, codeblockName: str):
+def _reformat_codeblock_tags(tags: list[dict], codeblock_type: str, codeblock_action: str, applied_tags: dict[str, str]):
     """
-    Turns data.json tag items into DiamondFire formatted tag items
+    Turns tag objects into DiamondFire formatted tag items
     """
-    reformattedTags = []
-    for tagItem in tags:
-        actionValue = codeblockName if 'action' not in tagItem else tagItem['action']
-        newTagItem = {
+
+    def format_tag(option: str, name: str):
+        return {
             'item': {
                 'id': 'bl_tag',
-                'data': {
-                    'option': tagItem['option'],
-                    'tag': tagItem['tag'],
-                    'action': actionValue,
-                    'block': codeblockType
-                }
+                'data': {'option': option, 'tag': name, 'action': codeblock_action, 'block': codeblock_type}
             },
-            'slot': tagItem['slot']
+            'slot': tag_item['slot']
         }
-        reformattedTags.append(newTagItem)
-    return reformattedTags
-
-
-def _getCodeblockTags(codeblockType: str, codeblockName: str):
-    """
-    Get tags for the specified codeblock type and name
-    """
-    tags = None
-    if codeblockType in TAGDATA_EXTRAS_KEYS:
-        tags = TAGDATA['extras'][codeblockType]
-    else:
-        tags = TAGDATA[codeblockType].get(codeblockName)
-    return _reformatCodeblockTags(tags, codeblockType, codeblockName)
-
-
-def _buildBlock(codeblock: CodeBlock, includeTags: bool):
-    """
-    Builds a properly formatted block from a CodeBlock object.
-    """
-    finalBlock = codeblock.data.copy()
-    codeblockType = codeblock.data.get('block')
-    
-    # add target if necessary ('Selection' is the default when 'target' is blank)
-    if codeblockType in TARGET_CODEBLOCKS and codeblock.target != DEFAULT_TARGET:
-        finalBlock['target'] = codeblock.target.getStringValue()
     
-    # add items into args
-    finalArgs = [arg.format(slot) for slot, arg in enumerate(codeblock.args) if arg.type in VARIABLE_TYPES]
-    
-    # check for unrecognized name, add tags
-    if codeblockType is not None:  # for brackets
-        if codeblockType not in TAGDATA_EXTRAS_KEYS and codeblock.name not in ALL_CODEBLOCK_NAMES:
-            _warnUnrecognizedName(codeblockType, codeblock.name)
-        elif includeTags:
-            tags = _getCodeblockTags(codeblockType, codeblock.name)
-            if len(finalArgs) + len(tags) > 27:
-                finalArgs = finalArgs[:(27-len(tags))]  # trim list if over 27 elements
-            finalArgs.extend(tags)  # add tags to end
-    
-    finalBlock['args'] = {'items': finalArgs}
-    return finalBlock
+    valid_applied_tags = _check_applied_tags(tags, applied_tags, codeblock_action)
+    reformatted_tags = []
+    for tag_item in tags:
+        tag_name = tag_item['name']
+        tag_option = tag_item['default']
+        if tag_name in valid_applied_tags:
+            tag_option = valid_applied_tags[tag_name]
 
+        new_tag_item = format_tag(tag_option, tag_name)
+        reformatted_tags.append(new_tag_item)
+    return reformatted_tags
 
-def _dfEncode(jsonString: str) -> str:
+
+def _get_codeblock_tags(codeblock_type: str, codeblock_name: str, applied_tags: dict[str, str]):
     """
-    Encodes a stringified json.
+    Get tags for the specified codeblock type and name
     """
-    encodedString = gzip.compress(jsonString.encode('utf-8'))
-    return base64.b64encode(encodedString).decode('utf-8')
+    action_data = CODEBLOCK_DATA[codeblock_type][codeblock_name]
+    if 'deprecatedNote' in action_data:
+        warn(f'Action "{codeblock_name}" is deprecated: {action_data["deprecatedNote"]}')
+    tags = action_data['tags']
+    return _reformat_codeblock_tags(tags, codeblock_type, codeblock_name, applied_tags)
 
 
-def getTemplateItem(templateCode: str, name: str, author: str) -> NbtItem:
+def _get_template_item(template_code: str, name: str, author: str) -> NbtItem:
     now = datetime.datetime.now()
 
-    templateItem = NbtItem('yellow_shulker_box')
-    templateItem.set_name(f'&x&f&f&5&c&0&0>> &x&f&f&c&7&0&0{name}')
-    templateItem.set_lore([
+    template_item = NbtItem('yellow_shulker_box')
+    template_item.set_name(f'&x&f&f&5&c&0&0>> &x&f&f&c&7&0&0{name}')
+    template_item.set_lore([
         f'&8Author: {author}',
         f'&8Date: {now.strftime("%Y-%m-%d")}',
         '',
@@ -205,275 +210,386 @@ def getTemplateItem(templateCode: str, name: str, author: str) -> NbtItem:
         '&7https://github.com/Amp63/pyre'
     ])
     
-    pbvTag = {
-        'hypercube:codetemplatedata': f'{{"author":"{author}","name":"{name}","version": 1,"code":"{templateCode}"}}',
+    pbv_tag = {
+        'hypercube:codetemplatedata': f'{{"author":"{author}","name":"{name}","version": 1,"code":"{template_code}"}}',
         'hypercube:pyre_creation_timestamp': now.timestamp()
     }
-    templateItem.set_tag('PublicBukkitValues', pbvTag, raw=True)
+    template_item.set_custom_data('PublicBukkitValues', pbv_tag, raw=True)
 
-    return templateItem
+    return template_item
 
 
-def sendRecode(templateCode: str, name: str='Unnamed Template', author: str='pyre') -> int:
+class DFTemplate:
     """
-    Sends a template to DiamondFire via recode item api.
-
-    :param str templateCode: The code for the template as a base64 string.
-    :param str name: The name of the template.
-    :param str author: The author of the template.
-
-    :return: status code
-        - `0` = Success
-        - `1` = Connection refused
-        - `2` = Other socket error
+    Represents a DiamondFire code template.
     """
+    def __init__(self, codeblocks: list[CodeBlock], author: str='pyre'):
+        self.codeblocks = codeblocks
+        self.author = author
     
-    templateItem = getTemplateItem(templateCode, name, author)
-    data = {'type': 'nbt', 'source': f'pyre Template - {name}', 'data': templateItem.get_nbt()}
-    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-    try:
-        s.connect(('127.0.0.1', 31372))
-    except ConnectionRefusedError:
-        print(f"""{COL_ERROR}Could not connect to recode item API. Possible problems:
-    - Minecraft is not open
-    - Recode is not installed (get it here: https://modrinth.com/mod/recode or join the discord here: https://discord.gg/GWxWtcwA2C){COL_RESET}""")
-        s.close()
-        return 1
-    
-    s.send((str(data) + '\n').encode('utf-8'))
-    received = json.loads(s.recv(1024).decode())
-    status = received['status']
-    s.close()
-    time.sleep(0.5)
-
-    if status == 'success':
-        print(f'{COL_SUCCESS}Template sent to client successfully.{COL_RESET}')
-        return 0
-    error = received['error']
-    print(f'{COL_ERROR}Error sending template: {error}{COL_RESET}')
-    return 2
-
-
-def sendCodeClient(templateCode: str, name: str='Unnamed Template', author: str='pyre') -> int:
-    try:
-        ws = websocket.WebSocket()
-        ws.connect(CODECLIENT_URL)
-        print(f'{COL_SUCCESS}Connected. {COL_WARN}Please run /auth in game.{COL_RESET}')
-        
-        ws.recv()  # auth response
 
-        templateItem = getTemplateItem(templateCode, name, author)
-        command = f'give {templateItem.get_nbt()}'
-        ws.send(command)
-        ws.close()
+    def _get_template_name(self):
+        first_block_data = self.codeblocks[0].data
+        if 'data' in first_block_data:
+            name = first_block_data['data']
+            return name if name else 'Unnamed Template'
+        return first_block_data['block'] + '_' + first_block_data['action']
 
-        print(f'{COL_SUCCESS}Template sent to client successfully.{COL_RESET}')
-        return 0
-        
-    except Exception as e:
-        if isinstance(e, ConnectionRefusedError):
-            print(f'{COL_ERROR}Could not connect to CodeClient API. Possible problems:')
-            print(f'    - Minecraft is not open')
-            print(f'    - CodeClient is not installed (get it here: https://modrinth.com/mod/codeclient)')
-            print(f'    - CodeClient API is not enabled (enable it in CodeClient general settings)')
-            return 1
-        
-        print(f'Connection failed: {e}')
-        return 2
 
+    def __repr__(self) -> str:
+        return f'DFTemplate(name: "{self._get_template_name()}", author: "{self.author}", codeblocks: {len(self.codeblocks)})'
 
-class DFTemplate:
-    """
-    Represents a DiamondFire code template.
-    """
-    def __init__(self, name: str=None, author: str='pyre'):
-        self.codeBlocks: List[CodeBlock] = []
-        self.closebracket = None
-        self.name = name
-        self.author = author
 
+    @staticmethod
+    def from_code(template_code: str):
+        """
+        Create a template object from an existing template code.
+        """
+        template_dict = json.loads(df_decode(template_code))
+        codeblocks: list[CodeBlock] = []
+        for block_dict in template_dict['blocks']:
+            block_tags = get_default_tags(block_dict.get('block'), block_dict.get('action'))
+            if 'args' in block_dict:
+                block_args = []
+                for item_dict in block_dict['args']['items']:
+                    if item_dict['item'].get('id') == 'bl_tag':
+                        tag_data = item_dict['item']['data']
+                        block_tags[tag_data['tag']] = tag_data['option']
+                    parsed_item = item_from_dict(item_dict['item'])
+                    if parsed_item is not None:
+                        block_args.append(parsed_item)
+            block_target = Target(TARGETS.index(block_dict['target'])) if 'target' in block_dict else DEFAULT_TARGET
+
+            codeblock_type = block_dict.get('block')
+
+            if codeblock_type is None:
+                codeblock = CodeBlock.new_bracket(block_dict['direct'], block_dict['type'])
+            if codeblock_type == 'else':
+                codeblock = CodeBlock.new_else()
+            elif codeblock_type in DYNAMIC_CODEBLOCKS:
+                codeblock = CodeBlock.new_data(codeblock_type, block_dict['data'], block_args, block_tags)
+            elif 'action' in block_dict:
+                codeblock = CodeBlock.new_action(codeblock_type, block_dict['action'], block_args, block_tags, block_target)
+            codeblocks.append(codeblock)
+        
+        return DFTemplate(codeblocks)
 
-    def _setTemplateName(self, firstBlock):
-        if self.name is not None:
-            return
-        if 'data' in firstBlock:
-            self.name = firstBlock['data']
-            if not self.name:
-                self.name = 'Unnamed Template'
+    
+    def insert(self, insert_codeblocks: CodeBlock|list[CodeBlock], index: int=-1) -> "DFTemplate":
+        """
+        Insert `insert_codeblocks` into this template at `index`.
+
+        :param CodeBlock|list[CodeBlock] insert_codeblocks: The block(s) to insert
+        :param int index: The index to insert at.
+        :return: self
+        """
+        if isinstance(insert_codeblocks, list):
+            insert_codeblocks = list(flatten(insert_codeblocks))
+            if index == -1:
+                self.codeblocks.extend(insert_codeblocks)
+            else:
+                self.codeblocks[index:index+len(insert_codeblocks)] = insert_codeblocks
+        elif isinstance(insert_codeblocks, CodeBlock):
+            self.codeblocks.insert(index, insert_codeblocks)
         else:
-            self.name = firstBlock['block'] + '_' + firstBlock['action']
+            raise PyreException('Expected CodeBlock or list[CodeBlock] to insert.')
+        return self
 
 
-    def build(self, includeTags: bool=True) -> str:
+    def build(self, include_tags: bool=True) -> str:
         """
         Build this template.
 
-        :param bool includeTags: If True, include item tags in code blocks. Otherwise omit them.
+        :param bool include_tags: If True, include item tags in code blocks. Otherwise omit them.
         :return: String containing encoded template data.
         """
-        templateDictBlocks = [_buildBlock(codeblock, includeTags) for codeblock in self.codeBlocks]
-        templateDict = {'blocks': templateDictBlocks}
-        firstBlock = templateDictBlocks[0]
-        if firstBlock['block'] not in TEMPLATE_STARTERS:
-            _warn('Template does not start with an event, function, or process.')
-
-        self._setTemplateName(firstBlock)
-
-        print(f'{COL_SUCCESS}Template built successfully.{COL_RESET}')
-
-        jsonString = json.dumps(templateDict, separators=(',', ':'))
-        return _dfEncode(jsonString)
+        template_dict_blocks = [codeblock.build(include_tags) for codeblock in self.codeblocks]
+        template_dict = {'blocks': template_dict_blocks}
+        first_block = template_dict_blocks[0]
+        if first_block['block'] not in TEMPLATE_STARTERS:
+            warn('Template does not start with an event, function, or process.')
+
+        json_string = json.dumps(template_dict, separators=(',', ':'))
+        return df_encode(json_string)
     
 
-    def buildAndSend(self, sendMethod: Literal['recode', 'codeclient']='recode', includeTags: bool=True) -> int:
+    def build_and_send(self, method: Literal['recode', 'codeclient'], include_tags: bool=True) -> int:
         """
         Builds this template and sends it to DiamondFire automatically.
         
-        :param bool includeTags: If True, include item tags in code blocks. Otherwise omit them.
+        :param bool include_tags: If True, include item tags in code blocks. Otherwise omit them.
         """
-        templateCode = self.build(includeTags)
-        if sendMethod == 'recode':
-            return sendRecode(templateCode, name=self.name, author=self.author)
-        if sendMethod == 'codeclient':
-            return sendCodeClient(templateCode, name=self.name, author=self.author)
-        return -1
+        template_code = self.build(include_tags)
+        template_item = _get_template_item(template_code, self._get_template_name(), self.author)
+        return template_item.send_to_minecraft(method, 'pyre')
     
-
-    def clear(self):
+    
+    def generate_script(self, output_path: str, indent_size: int=4, literal_shorthand: bool=True, var_shorthand: bool=False):
         """
-        Clears this template's data.
+        Generate an equivalent python script for this template.
+
+        :param str output_path: The file path to write the script to.
+        :param int indent_size: The multiple of spaces to add when indenting lines.
+        :param bool literal_shorthand: If True, `text` and `num` items will be written as strings and ints respectively.
+        :param bool var_shorthand: If True, all variables will be written using variable shorthand.
         """
-        self.__init__()
-    
+        flags = GeneratorFlags(indent_size, literal_shorthand, var_shorthand)
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write(generate_script(self, flags))
 
-    def _openbracket(self, btype: Literal['norm', 'repeat']='norm'):
-        bracket = CodeBlock('Bracket', data={'id': 'bracket', 'direct': 'open', 'type': btype})
-        self.codeBlocks.append(bracket)
-        self.closebracket = btype
-    
 
-    # command methods
-    def playerEvent(self, name: str):
-        cmd = CodeBlock(name, data={'id': 'block', 'block': 'event', 'action': name})
-        self.codeBlocks.append(cmd)
-    
+def _assemble_template(starting_block: CodeBlock, codeblocks: list[CodeBlock], author: str|None) -> DFTemplate:
+    """
+    Create a DFTemplate object from a starting block and a list of codeblocks.
+    `codeblocks` can contain nested lists of CodeBlock objects, so it must be flattened.
+    """
+    if author is None:
+        author = 'pyre'
+    template_codeblocks = [starting_block] + list(flatten(codeblocks))  # flatten codeblocks list and insert starting block
+    return DFTemplate(template_codeblocks, author)
 
-    def entityEvent(self, name: str):
-        cmd = CodeBlock(name, data={'id': 'block', 'block': 'entity_event', 'action': name})
-        self.codeBlocks.append(cmd)
-    
 
-    def function(self, name: str, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock('function', args, data={'id': 'block', 'block': 'func', 'data': name})
-        self.codeBlocks.append(cmd)
-    
+def player_event(event_name: str, codeblocks: list[CodeBlock]=(), author: str|None=None) -> DFTemplate:
+    """
+    Represents a Player Event codeblock.
 
-    def process(self, name: str):
-        cmd = CodeBlock('process', data={'id': 'block', 'block': 'process', 'data': name})
-        self.codeBlocks.append(cmd)
-    
+    :param str event_name: The name of the event. (Ex: "Join")
+    :param list[CodeBlock] codeblocks: The list of codeblocks in this template.
+    :param str|None author: The author of this template.
+    """
+    starting_block = CodeBlock.new_action('event', event_name, (), {})
+    return _assemble_template(starting_block, codeblocks, author)
 
-    def callFunction(self, name: str, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock('call_func', args, data={'id': 'block', 'block': 'call_func', 'data': name})
-        self.codeBlocks.append(cmd)
-    
 
-    def startProcess(self, name: str):
-        cmd = CodeBlock('start_process', data={'id': 'block', 'block': 'start_process', 'data': name})
-        self.codeBlocks.append(cmd)
+def entity_event(event_name: str, codeblocks: list[CodeBlock]=[], author: str|None=None) -> DFTemplate:
+    """
+    Represents an Entity Event codeblock.
 
+    :param str event_name: The name of the event. (Ex: "EntityDmg")
+    :param list[CodeBlock] codeblocks: The list of codeblocks in this template.
+    :param str|None author: The author of this template.
+    """
+    starting_block = CodeBlock.new_action('entity_event', event_name, (), {})
+    return _assemble_template(starting_block, codeblocks, author)
 
-    def playerAction(self, name: str, *args, target: Target=DEFAULT_TARGET):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock(name, args, target=target, data={'id': 'block', 'block': 'player_action', 'action': name})
-        self.codeBlocks.append(cmd)
-    
 
-    def gameAction(self, name: str, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock(name, args, data={'id': 'block', 'block': 'game_action', 'action': name})
-        self.codeBlocks.append(cmd)
-    
+def function(function_name: str, *args, tags: dict[str, str]={}, codeblocks: list[CodeBlock]=[], author: str|None=None) -> DFTemplate:
+    """
+    Represents a Function codeblock.
 
-    def entityAction(self, name: str, *args, target: Target=DEFAULT_TARGET):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock(name, args, target=target, data={'id': 'block', 'block': 'entity_action', 'action': name})
-        self.codeBlocks.append(cmd)
-    
+    :param str event_name: The name of the function.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    :param list[CodeBlock] codeblocks: The list of codeblocks in this template.
+    :param str|None author: The author of this template.
+    """
+    starting_block = CodeBlock.new_data('func', function_name, args, tags)
+    return _assemble_template(starting_block, codeblocks, author)
 
-    def ifPlayer(self, name: str, *args, target: Target=DEFAULT_TARGET, inverted: bool=False):
-        args = _convertDataTypes(args)
-        data = {'id': 'block', 'block': 'if_player', 'action': name}
-        _addInverted(data, inverted)
-        cmd = CodeBlock(name, args, target=target, data=data)
-        self.codeBlocks.append(cmd)
-        self._openbracket()
-    
 
-    def ifVariable(self, name: str, *args, inverted: bool=False):
-        args = _convertDataTypes(args)
-        data = {'id': 'block', 'block': 'if_var', 'action': name}
-        _addInverted(data, inverted)
-        cmd = CodeBlock(name, args, data=data)
-        self.codeBlocks.append(cmd)
-        self._openbracket()
-    
+def process(process_name: str, *args, tags: dict[str, str]={}, codeblocks: list[CodeBlock]=[], author: str|None=None) -> DFTemplate:
+    """
+    Represents a Process codeblock.
 
-    def ifGame(self, name: str, *args, inverted: bool=False):
-        args = _convertDataTypes(args)
-        data = {'id': 'block', 'block': 'if_game', 'action': name}
-        _addInverted(data, inverted)
-        cmd = CodeBlock(name, args, data=data)
-        self.codeBlocks.append(cmd)
-        self._openbracket()
-    
+    :param str event_name: The name of the process.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    :param list[CodeBlock] codeblocks: The list of codeblocks in this template.
+    :param str|None author: The author of this template.
+    """
+    starting_block = CodeBlock.new_data('process', process_name, args, tags)
+    return _assemble_template(starting_block, codeblocks, author)
 
-    def ifEntity(self, name: str, *args, target: Target=DEFAULT_TARGET, inverted: bool=False):
-        args = _convertDataTypes(args)
-        data = {'id': 'block', 'block': 'if_entity', 'action': name}
-        _addInverted(data, inverted)
-        cmd = CodeBlock(name, args, target=target, data=data)
-        self.codeBlocks.append(cmd)
-        self._openbracket()
 
+def call_function(function_name: str, *args) -> CodeBlock:
+    """
+    Represents a Call Function codeblock.
 
-    def else_(self):
-        cmd = CodeBlock('else', data={'id': 'block', 'block': 'else'})
-        self.codeBlocks.append(cmd)
-        self._openbracket()
-    
+    :param str event_name: The name of the function.
+    :param tuple args: The argument items to include.
+    """
+    return CodeBlock.new_data('call_func', function_name, args, {})
 
-    def repeat(self, name: str, *args, subAction: str=None):
-        args = _convertDataTypes(args)
-        data = {'id': 'block', 'block': 'repeat', 'action': name}
-        if subAction is not None:
-            data['subAction'] = subAction
-        cmd = CodeBlock(name, args, data=data)
-        self.codeBlocks.append(cmd)
-        self._openbracket('repeat')
 
+def start_process(process_name: str, *args, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents a Call Function codeblock.
 
-    def bracket(self, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock('Bracket', data={'id': 'bracket', 'direct': 'close', 'type': self.closebracket})
-        self.codeBlocks.append(cmd)
-    
+    :param str event_name: The name of the function.
+    :param tuple args: The argument items to include.
+    """
+    return CodeBlock.new_data('start_process', process_name, args, tags)
 
-    def control(self, name: str, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock(name, args, data={'id': 'block', 'block': 'control', 'action': name})
-        self.codeBlocks.append(cmd)
-    
 
-    def selectObject(self, name: str, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock(name, args, data={'id': 'block', 'block': 'select_obj', 'action': name})
-        self.codeBlocks.append(cmd)
-    
+def player_action(action_name: str, *args, target: Target=DEFAULT_TARGET, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents a Player Action codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param Target target: The target for the action.
+    :param dict[str, str] tags: The tags to include.
+    """
+    return CodeBlock.new_action('player_action', action_name, args, tags, target=target)
+
+
+def entity_action(action_name: str, *args, target: Target=DEFAULT_TARGET, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents an Entity Action codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param Target target: The target for the action.
+    :param dict[str, str] tags: The tags to include.
+    """
+    return CodeBlock.new_action('entity_action', action_name, args, tags, target=target)
+
+
+def game_action(action_name: str, *args, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents a Game Action codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    """
+    return CodeBlock.new_action('game_action', action_name, args, tags)
+
+
+def if_player(action_name: str, *args, target: Target=DEFAULT_TARGET, tags: dict[str, str]={}, inverted: bool=False, codeblocks: list[CodeBlock]=[]) -> list[CodeBlock]:
+    """
+    Represents an If Player codeblock.
+
+    :param str action_name: The name of the condition.
+    :param tuple args: The argument items to include.
+    :param Target target: The target for the condition.
+    :param dict[str, str] tags: The tags to include.
+    :param bool inverted: Whether the condition should be inverted.
+    :param list[CodeBlock] codeblocks: The list of codeblocks inside the brackets.
+    """
+    return [
+        CodeBlock.new_conditional('if_player', action_name, args, tags, inverted, target),
+        CodeBlock.new_bracket('open', 'norm')
+    ] + list(codeblocks) + [
+        CodeBlock.new_bracket('close', 'norm')
+    ]
+
+def if_entity(action_name: str, *args, target: Target=DEFAULT_TARGET, tags: dict[str, str]={}, inverted: bool=False, codeblocks: list[CodeBlock]=[]) -> list[CodeBlock]:
+    """
+    Represents an If Entity codeblock.
+
+    :param str action_name: The name of the condition.
+    :param tuple args: The argument items to include.
+    :param Target target: The target for the condition.
+    :param dict[str, str] tags: The tags to include.
+    :param bool inverted: Whether the condition should be inverted.
+    :param list[CodeBlock] codeblocks: The list of codeblocks inside the brackets.
+    """
+    return [
+        CodeBlock.new_conditional('if_entity', action_name, args, tags, inverted, target),
+        CodeBlock.new_bracket('open', 'norm')
+    ] + list(codeblocks) + [
+        CodeBlock.new_bracket('close', 'norm')
+    ]
+
+
+def if_game(action_name: str, *args, tags: dict[str, str]={}, inverted: bool=False, codeblocks: list[CodeBlock]=[]) -> list[CodeBlock]:
+    """
+    Represents an If Game codeblock.
+
+    :param str action_name: The name of the condition.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    :param bool inverted: Whether the condition should be inverted.
+    :param list[CodeBlock] codeblocks: The list of codeblocks inside the brackets.
+    """
+    return [
+        CodeBlock.new_conditional('if_game', action_name, args, tags, inverted),
+        CodeBlock.new_bracket('open', 'norm')
+    ] + list(codeblocks) + [
+        CodeBlock.new_bracket('close', 'norm')
+    ]
+
+
+def if_variable(action_name: str, *args, tags: dict[str, str]={}, inverted: bool=False, codeblocks: list[CodeBlock]=[]) -> list[CodeBlock]:
+    """
+    Represents an If Variable codeblock.
+
+    :param str action_name: The name of the condition.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    :param bool inverted: Whether the condition should be inverted.
+    :param list[CodeBlock] codeblocks: The list of codeblocks inside the brackets.
+    """
+    return [
+        CodeBlock.new_conditional('if_var', action_name, args, tags, inverted),
+        CodeBlock.new_bracket('open', 'norm')
+    ] + list(codeblocks) + [
+        CodeBlock.new_bracket('close', 'norm')
+    ]
+
+
+def else_(codeblocks: list[CodeBlock]=[]) -> list[CodeBlock]:
+    """
+    Represents an Else codeblock.
+
+    :param list[CodeBlock] codeblocks: The list of codeblocks inside the brackets.
+    """
+    return [
+        CodeBlock.new_else(),
+        CodeBlock.new_bracket('open', 'norm')
+    ] + list(codeblocks) + [
+        CodeBlock.new_bracket('close', 'norm')
+    ]
 
-    def setVariable(self, name: str, *args):
-        args = _convertDataTypes(args)
-        cmd = CodeBlock(name, args, data={'id': 'block', 'block': 'set_var', 'action': name})
-        self.codeBlocks.append(cmd)
+
+def repeat(action_name: str, *args, tags: dict[str, str]={}, sub_action: str|None=None, inverted: bool=False, codeblocks: list[CodeBlock]=[]) -> CodeBlock:
+    """
+    Represents a Repeat codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    :param str|None sub_action: The sub-action for the repeat action (Only relevant for `While`)
+    :param bool inverted: Whether the sub-action condition should be inverted.
+    :param list[CodeBlock] codeblocks: The list of codeblocks inside the brackets.
+    """
+    return [
+        CodeBlock.new_repeat(action_name, args, tags, sub_action, inverted),
+        CodeBlock.new_bracket('open', 'repeat')
+    ] + list(codeblocks) + [
+        CodeBlock.new_bracket('close', 'repeat')
+    ]
+
+
+def control(action_name: str, *args, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents a Control codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    """
+    return CodeBlock.new_action('control', action_name, args, tags)
+
+
+def select_object(action_name: str, *args, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents a Select Object codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    """
+    return CodeBlock.new_action('select_obj', action_name, args, tags) 
+
+
+def set_variable(action_name: str, *args, tags: dict[str, str]={}) -> CodeBlock:
+    """
+    Represents a Set Variable codeblock.
+
+    :param str action_name: The name of the action.
+    :param tuple args: The argument items to include.
+    :param dict[str, str] tags: The tags to include.
+    """
+    return CodeBlock.new_action('set_var', action_name, args, tags)