diff --git a/README.md b/README.md index ecac393..f2999a0 100644 --- a/README.md +++ b/README.md @@ -3,131 +3,186 @@ A desktop version of the renowned OpenComputers emulator Ocelot. -[Download the latest build][download] / [mirror][download-mirror] +[**Download** the latest build][download] / [mirror][download-mirror] ## Why -You might already be happy with your choice of an OC emulator; after all, there -is already a plenty of them. -So why would you want to reconsider your life choices now all of a sudden? +You might already be happy with your choice of an OC emulator; +there is a plenty of them, after all. +Why would you want to reconsider your life choices now all of a sudden? A fine question, indeed; perhaps, a list of features will persuade you. ### Powered by ocelot-brain At the heart of this emulator is [ocelot-brain][ocelot-brain] (uh, don't ask me), -which is essentially the source code of OpenComputers stripped of everything -Minecraft-specific and packaged as a Scala library. +which is essentially the source code of OpenComputers decoupled of everything +Minecraft-specific and repurposed as a Scala library. This makes Ocelot Desktop **the most accurate emulator** ever made. -Your programs will run on the same version of Lua as used by the mod and have +Your programs will run on the Lua implementation used by the mod and exhibit similar timings. The performance and memory constraints present in OC are also emulated. ### Customizable setups -Computers can have the following components: +Taylor your computer build to your needs! +We provide a variety of components to choose from: -- the 3 tiers of graphics cards -- all kinds of network cards (wired, wireless) -- a linked card -- an internet card -- a sound card (Computronics) -- a redstone card in the both tiers -- a data card (again, you can pick any of the three tiers) +- graphics cards +- network cards (wired, wireless) +- linked cards +- internet cards +- redstone cards (including the second tier!) +- data cards - hard disks -- a floppy disk (in T3+ computer cases only) +- floppy disks (in T3+ computer cases only, just like in OpenComputers) -The choice is restricted by the tier of a computer case, just like in -OpenComputers, to avoid building impossible configurations. -Oh, did I forget to mention that Ocelot Desktop has both the CPUs and the APUs? -Memory can likewise be installed according to your needs. +Feel limited by the vanilla cards? +No problem — we've even integrated some components from popular addons! -If one computer is not enough, you can add another one. -Or two, or a thousand, as long as your host doesn't collapse under the load, -of course. -The network cards are there for a reason — these newly spawned machines can -communicate with each other. -And relays may help you manage the wired networks. +![Addon showcase][addon-showcase] -Or, instead of employing an army of computers, you might want to connect a dozen -of screens to a single machine, like in the movies. -No problem — we've got that covered, too. +- **Computronics:** + - `computer.beep()` does not excite your music sense enough? + Check out the **sound card**'s synthesis engine, + or string notes together on a bunch of **note blocks**! -### Pretty graphical interface + - You have privacy concerns? + An ultra-precision blast of the **self-destructing card** might save your day! + + - If, on the contrary, you're the kind to violate the privacy of others, + we've got a **camera** that reads video data from a real webcam. + + - Those who seem to find no color in their life may appreciate the + **colorful lamps**. + Their iridescent glow will provide comfort in the darkest hour. + And they won't desert you. + +- **OpenFM:** for those lo-fi beats to chill and relax to while writing code. + +We'll make sure your setups are grounded in reality +by having the maximum card tier in a slot depend on your computer case. +Oh, did I forget to mention Ocelot Desktop has APUs as well? + +Explore the wonders of distributed computing by adding a couple of other +computers to your workspace. +(Or a thousand — if you think your host can handle this.) +Network cards allow these newly spawned machines to talk to each other. +And relays may prove useful to manage the wired networks. + +Perhaps, instead of enlisting a computer army, +you want to attach a dozen of screens to a single machine +(as they do in the movies). +Well, no problem — we've got that covered, too. + +### Gorgeous graphical interface ![GUI][gui] -A slick interface allows you to customize the setup to your liking. -Add more computers, organize the connections between components, build complex -setups, and manage your screen real estate to avoid distractions. +Manage your screen real estate to avoid distractions. +All nodes are draggable, as are windows. +And screen windows in particular are also resizeable — +click and drag the bottom-right corner if they take up too much space. +Or hold Shift and let the window consume it all. -Many additional options are hidden in the context menu — try hitting the -right mouse button on the various things. -For example, components will let you copy their address to the clipboard, and -right-clicking on the TPS counter on the bottom allows you to change the -simulation speed. +![Window scaling][window-scaling] -The emulator uses hardware acceleration to offload the daunting task of -rendering its interface to a specialized device, so make sure you have a OpenGL -2.1-capable graphics card. +Many additional options are hidden in the context menus — +try hitting the right mouse button on various things. +For example, components will let you copy their address to the clipboard, +and right-clicking on the TPS counter (on the bottom right) +allows you to change the simulation speed. + +![TPS rate menu][tps-menu] + +Ocelot Desktop uses hardware acceleration to offload the daunting task of +rendering its interface to a special-purposed device (your GPU), +so make sure you have an **OpenGL 2.1-capable** graphics card. +(Though, honestly, it's harder to find one that isn't, really.) ### Persistable workspaces -It would be sad if, after all the hard work you put into adjusting the -workspace, you have to do that again. +Imagine putting many hours into wiring things up only to have to do it all from +scratch the next time you open the emulator. +That... would be sad and disappointing. I mean, OpenComputers can persist its machines just fine, right? -By basing the emulator on its code, we've essentially inherited the ability -to save workspaces on the disk and load them afterwards. +Good news: by reusing its code, we've essentially inherited the ability +to save workspaces on the disk and load them afterwards! Just in case, Ocelot Desktop will warn you if you smash the quit button without saving. +We'd rather you didn't feel sad and disappointed. ### Cool features -![Performance graphs][graphs] +![Performance graphs][perf-graphs] ![Sound card GUI][sound-card] A few smaller features are worth mentioning, too: -- Screens are resizeable — drag the bottom-right corner. -- Windows are labeled with the corresponding block's address; however, you can - set a custom label — look for an option in the context menu. -- The button in a computer case window shows the performance graphs: - the used memory, processor time and call budget. -- Hold the Ctrl key while dragging blocks to have them snap to the grid. +- Windows show the corresponding block's address by default. + However, you can relabel them: look for the option in the context menu. +- The button ![][drawer-button] at the bottom of a computer case window + shows performance graphs: the memory, processor time, and call budget. +- Hold the Ctrl key while dragging blocks to snap them to the grid. ## Download -Decided to give Ocelot Desktop a shot? [Download the latest build][download] / [mirror][download-mirror] +Decided to give Ocelot Desktop a shot? -## How to build it? -Just import the project in your favorite IDE. -Make sure to have Scala and SBT installed (manually or through IDE). +[**Download** the latest build][download] / [mirror][download-mirror] -Ocelot Brain library is added as a Git submodule, so do not forget to fetch it too. -Something like `git submodule update --init --recursive` should do the trick. +## Hacking +Just import the project in your favorite IDE. +Make sure to have Scala and SBT installed (your IDE may assist you with that). -Use `sbt run` to start Ocelot Desktop. Use `sbt assembly` to generate JAR file. -(It will appear at `target/scala-2.13/ocelot-desktop.jar` location.) +We include [ocelot-brain][] as a Git submodule: don't forget to fetch it! -If the compiler is complaining about missing BuildInfo class, or the version in -the window title / logs looks outdated, use `sbt buildInfo` to generate fresh class. +```sh +$ git submodule update --init --recursive +``` + +To build from source and start Ocelot Desktop, type: + +```sh +$ sbt run +``` + +If you want to get a JAR, use this: + +```sh +$ sbt assembly +``` + +(You'll find it at `target/scala-2.13/ocelot-desktop.jar`.) + +In case you see the compiler complain about `BuildInfo` or just want to refresh +the version displayed in the window title and the logs, run: + +```sh +$ sbt buildInfo +``` ## Credits -- **LeshaInc**, the author and maintainer of Ocelot Desktop. -- **Totoro**, the creator of ocelot-brain and ocelot-online. -- **bpm140**, who created marvelous Ocelot Desktop landing page. -- **rason**, who stirred the development at the critical moment. -- **NE0**, the bug extermination specialist. -- **ECS**, who fearlessly jumped right into Scala jungle. -- **fingercomp**, who wrote this README. +- **LeshaInc:** the original author and maintainer of Ocelot Desktop. +- **Totoro:** the creator of [ocelot-brain][] and [ocelot.online][ocelot-online]. +- **bpm140:** produced the marvelous Ocelot Desktop landing page. +- **rason:** stirred the development at the critical moment! +- **NE0:** the bug extermination specialist. +- **ECS:** leaped fearlessly into the Scala jungle. +- **fingercomp:** wrote this README. ## See also -- [Ocelot Desktop][ocelot-desktop] web page (link to the latest build, FAQ) -- [ocelot.online][ocelot-online], a rudimentary web version of Ocelot -- [ocelot-brain][ocelot-brain], the backend library of Ocelot Desktop +- The [Ocelot Desktop][ocelot-desktop] web page + (links to the latest build, FAQ). +- [ocelot.online][ocelot-online], a rudimentary web version of Ocelot. +- [ocelot-brain][], the backend library of Ocelot Desktop. - [#cc.ru on IRC][irc] if you have any questions - (Russian, but we're fine with English too) -- [Discord][discord] if you prefer so (we will not judge) + (Russian, but we're fine with English too). +- Or [Discord][discord] if that's your fancy (we won't judge). -[banner]: https://i.imgur.com/OzkpQZv.png +[banner]: ./assets/banner.png "The Ocelot banner" [download]: https://cc-ru.gitlab.io/ocelot/ocelot-desktop/ocelot.jar [download-mirror]: https://ocelot.fomalhaut.me/ocelot.jar -[gui]: https://i.imgur.com/O4bF7I8.png -[graphs]: https://i.imgur.com/mG8UjhV.png -[sound-card]: https://i.imgur.com/gnh3D6N.png +[addon-showcase]: ./assets/addon-showcase.png "A workspace with colorful lamps and an OpenFM radio." +[gui]: ./assets/gui.png "A screenshot of the GUI." +[window-scaling]: ./assets/window-scale.gif "Demonstrates the screen scaling." +[tps-menu]: ./assets/tps.png "The simulation speed menu (right-click on the TPS)." +[perf-graphs]: ./assets/perf-graphs.gif "A demo of performance graphs." +[sound-card]: ./assets/sound-card.gif "Shows the sound card UI while playing a melody." +[drawer-button]: ./sprites/buttons/BottomDrawerOpen.png [ocelot-brain]: https://gitlab.com/cc-ru/ocelot/ocelot-brain [ocelot-online]: https://ocelot.fomalhaut.me/ [ocelot-desktop]: https://ocelot.fomalhaut.me/desktop/ diff --git a/assets/addon-showcase.png b/assets/addon-showcase.png new file mode 100644 index 0000000..d050320 Binary files /dev/null and b/assets/addon-showcase.png differ diff --git a/assets/banner.png b/assets/banner.png new file mode 100644 index 0000000..96d65af Binary files /dev/null and b/assets/banner.png differ diff --git a/assets/gui.png b/assets/gui.png new file mode 100644 index 0000000..2882bce Binary files /dev/null and b/assets/gui.png differ diff --git a/assets/perf-graphs.gif b/assets/perf-graphs.gif new file mode 100644 index 0000000..9c92811 Binary files /dev/null and b/assets/perf-graphs.gif differ diff --git a/assets/sound-card.gif b/assets/sound-card.gif new file mode 100644 index 0000000..fd74ef4 Binary files /dev/null and b/assets/sound-card.gif differ diff --git a/assets/tps.png b/assets/tps.png new file mode 100644 index 0000000..ac7d7af Binary files /dev/null and b/assets/tps.png differ diff --git a/assets/window-scale.gif b/assets/window-scale.gif new file mode 100644 index 0000000..6df6e1a Binary files /dev/null and b/assets/window-scale.gif differ