|
1 | | ---- |
2 | | -description: A short introduction to ByteSkript, its uses, goals and applications. coverY: 0 |
3 | | ---- |
| 1 | +# ByteSkript |
4 | 2 |
|
5 | | -# 🎶 Introduction to ByteSkript |
6 | | - |
7 | | -## Overview |
8 | | - |
9 | | -#### Opus #11 |
| 3 | +### Opus #11 |
10 | 4 |
|
11 | 5 | An experimental language based on Skript (with no pre-eminent DSL dependencies) compiled to JVM bytecode. |
12 | 6 |
|
13 | | -### Visit the [documentation](https://moderocky.gitbook.io/byteskript/) and wiki [here](https://moderocky.gitbook.io/byteskript/). |
| 7 | +## Visit the [documentation](https://moderocky.gitbook.io/byteskript/) and wiki [here](https://moderocky.gitbook.io/byteskript/). |
14 | 8 |
|
15 | 9 | ByteSkript draws heavily from the original [Skript](https://github.com/SkriptLang/Skript/) language design, with some |
16 | 10 | minor structural adaptations to strengthen the language grammar, to remove some unnecessary jargon and make the language |
17 | 11 | more reliable. ByteSkript also increases interoperability with existing JVM languages. |
18 | 12 |
|
19 | | -{% hint style="info" %} |
20 | | -**ByteSkript is not affiliated with** [**SkriptLang**](https://github.com/SkriptLang/Skript/)**.**\ |
| 13 | +**ByteSkript is not affiliated with [SkriptLang](https://github.com/SkriptLang/Skript/).** |
| 14 | + |
21 | 15 | ByteSkript is a completely **new** implementation of the general guide and style of the 'Skript' language, with its own |
22 | 16 | language specification, goals and licence. |
23 | 17 |
|
24 | | -For clarity: SkriptLang's Skript implementation will be referred to as 'original' or 'minecraft' Skript. {% endhint %} |
25 | | - |
26 | | -### Goals |
27 | | - |
28 | | -1. Provide a more efficient, compiled alternative to original Skript.\ |
29 | | - Code will be compiled to JVM bytecode, with efficiency approaching or exceeding bytecode produced by `javac`. |
30 | | -2. Provide a stricter, stronger interpretation of the Skript language.\ |
31 | | - Structures and language elements follow stricter rules to prevent inconsistency. |
32 | | -3. Provide a version of Skript with no built-in domain dependencies.\ |
33 | | - No third-party libraries should be required to run scripts. |
34 | | -4. Provide a version of Skript applicable to multiple domains.\ |
35 | | - An extensible API should be provided to allow creation of syntax libraries. |
36 | | - |
37 | | -### Non-goals |
38 | | - |
39 | | -1. Not a replacement of the original Skript.\ |
40 | | - There will be no built-in minecraft functionality. |
41 | | -2. Provide no built-in domain-specific functionality.\ |
42 | | - The built-in Skript language library will have no syntax for third-party libraries or domains.\ |
43 | | - A minecraft server will not be required to run scripts. |
44 | | -3. No alteration to language fundamentals.\ |
45 | | - The layout, look, readability and core language components should keep parity with original Skript.\ |
46 | | - Some small changes will be made to improve readability and compile accuracy. |
47 | | - |
48 | | -Skript is designed to be beginner-friendly. Ideally, a user with no experience should be able to read Skript code and |
49 | | -understand its function. All instructions are written in basic English, avoiding niche programming terms and symbols |
50 | | -wherever possible. |
51 | | - |
52 | | -## Using ByteSkript |
53 | | - |
54 | | -ByteSkript provides **three** different executable Jar files for different purposes. |
55 | | - |
56 | | -Running these for the first time will create special folders in the run directory. |
57 | | - |
58 | | -| Name | Purpose | |
59 | | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
60 | | -| `skript/` | <p>This is where you can write your script files, with the extension <code>.bsk</code>.<br>All <code>.bsk</code> files in this directory and its subfolders will be compiled/loaded.</p> | |
61 | | -| `resources/` | <p>This is where you can put non-script files that you need in your output jar.<br>This is only used by the jar builder.</p> | |
62 | | -| `compiled/` | <p>If you are compiling your scripts to <code>.class</code> or <code>.jar</code> files, the output will go here.<br>This folder is never emptied, so make sure to delete any old versions before re-compiling.</p> | |
63 | | - |
64 | | -### SkriptLoader |
65 | | - |
66 | | -This is the simplest resource, used for loading (and running) user-created script files. |
67 | | - |
68 | | -Raw script files can be written and placed in the `skript/` folder. All scripts will be loaded internally, but no |
69 | | -classes or jar files will be written. |
70 | | - |
71 | | -The `on [script] load` event will be triggered for each script as an entry point. |
72 | | - |
73 | | -{% hint style="success" %} The ByteSkript compilers, language specification and compile-time API are available in this |
74 | | -resource, so advanced scripts may use dynamic loading to load extra skript code written at runtime! |
75 | | -{% endhint %} |
76 | | - |
77 | | -### SkriptClassCompiler |
78 | | - |
79 | | -This resource is used for generating compiled JVM `.class` files for each script in the `skript/` folder. The classes |
80 | | -produced by this are not directly executable, but may be useful for sharing and special loading. |
81 | | - |
82 | | -The compiled scripts will **not** be loaded or run. |
83 | | - |
84 | | -### SkriptJarBuilder |
85 | | - |
86 | | -This resource builds an executable jar containing all of the user-created scripts, resources and the ByteSkript |
87 | | -runtime (`skript` namespace and functions.) |
88 | | - |
89 | | -\ |
90 | | -This output jar can be run with `java -jar JarName.jar` and is distributable - it does not need anything as a |
91 | | -dependency. |
92 | | - |
93 | | -When executing this jar, all scripts will be loaded and the `on [script] load` event will be triggered for each script |
94 | | -as an entry point. |
95 | | - |
96 | | -{% hint style="danger" %} The ByteSkript standard compiler and compile-time API are **not** added to the output jar. {% |
97 | | -endhint %} |
98 | | - |
99 | | -{% hint style="success" %} The dynamic function on-the-fly compiler **is** available in this jar, so dynamic function |
100 | | -calls are available. {% endhint %} |
101 | | - |
102 | | -## Language Libraries |
103 | | - |
104 | | -Due to its fixed nature, the Skript language has always relied on third-party add-ons to add new syntax and |
105 | | -functionality for specific areas. |
106 | | - |
107 | | -ByteSkript achieves this through libraries, which can register compile-time and run-time functionality. |
108 | | - |
109 | | -There are two provided syntax APIs, labelled `v1` and `v2`. Both are available and easily accessible, but may be suited |
110 | | -to different tasks. |
111 | | - |
112 | | -Within the set of built-in functions in the `skript` namespace are some for accessing JVM resources which can be used to |
113 | | -build more advanced functionality. |
114 | | - |
115 | | -### API v1 |
116 | | - |
117 | | -The `v1` syntax API offers complete control of syntax, including writing bytecode instructions, look-aheads, additions, |
118 | | -etc. |
119 | | - |
120 | | -However, it also requires creating and individually registering (fairly complex) classes to add new syntax and language |
121 | | -structures. |
122 | | - |
123 | | -This is the most powerful syntax API, as it allows control of the result code at the VM-bytecode level for experienced |
124 | | -users. It is recommended for adding entirely new language structures or features with excessively-variable layouts. |
125 | | - |
126 | | -{% hint style="info" %} The implicit array creation syntax `(a, b, ...)` has to use the v1 API to create variable-size |
127 | | -arrays. {% endhint %} |
128 | | - |
129 | | -### API v2 |
130 | | - |
131 | | -The `v2` syntax API is significantly easier to use, but offers much less control over syntax. |
132 | | - |
133 | | -Syntax methods are given an annotation, and the class they belong to is registered to a library. This API is much more |
134 | | -suitable for property syntax, where creating a class for each one would be excessive. |
135 | | - |
136 | | -{% hint style="info" %} The v2 API is used internally by all of the I/O handler syntax. A lot of these are also forced |
137 | | -to extract or bridge. {% endhint %} |
138 | | - |
139 | | -### Libraries Used |
| 18 | +## Libraries Used |
140 | 19 |
|
141 | | -* [ObjectWeb ASM](https://asm.ow2.io)\ |
| 20 | +* [ObjectWeb ASM](https://asm.ow2.io) \ |
142 | 21 | A bytecode-assembling library used internally by the Java JDK.\ |
143 | 22 | Used for compiling complex syntax. |
144 | | -* [Mirror](https://github.com/Moderocky/Mirror)\ |
| 23 | +* [Mirror](https://github.com/Moderocky/Mirror) \ |
145 | 24 | An on-the-fly member access compiler, alternative to Java reflection.\ |
146 | 25 | Used for compiling dynamic method handles at runtime. |
147 | | -* [Foundation](https://github.com/Moderocky/Foundation)\ |
| 26 | +* [Foundation](https://github.com/Moderocky/Foundation) \ |
148 | 27 | A class-building framework to simplify method creation.\ |
149 | | - Used for compiling simple syntax.\ |
| 28 | + Used for compiling simple syntax. |
0 commit comments