1# neo
2
3![neo is AWESOME](assets/neo_is_awesome.gif)
4
5**WARNING: neo may cause discomfort and seizures in people with photosensitive epilepsy. User discretion is advised.**
6
7**neo** recreates the digital rain effect from "The Matrix". Streams of random
8characters will endlessly scroll down your terminal screen.
9
10Cool features:
11
12- Simulates the effect convincingly:
13  - Similar color palatte and uneven colors
14  - Glitchy characters
15  - Half-width katakana characters
16- Can display a message similar to the title crawl in the movies
17- Unicode support
18- Supports 16/256 colors and 32-bit color
19- Automatic detection of terminal color and Unicode support
20- Handles terminal resizing
21- Fully customizable colors and characters
22- Many key controls and command-line options for customization
23
24**neo** is best enjoyed with some good Scotch while listening to Aphex Twin and working on tech.
25
26## Prerequisites
27
28**neo** works with Linux, and it should work with other POSIX-compliant operating systems such as macOS and FreeBSD. Windows is not supported.
29
30The following packages are required to build and run **neo**:
31
32- autoconf: **neo** is built using autotools
33- autoconf-archive: required for some of the autoconf checks
34- build-essential: make and g++ are used for compilation
35- libncurses-dev: **neo** uses ncursesw to control the terminal
36
37You will need to ensure that your C++ compiler supports C++11 and that your autoconf version is at least 2.61. g++ and clang++ should both work for compilation.
38
39A fast terminal emulator such as Alacritty is highly recommended. neo can be a bit of a CPU hog, especially on large screens with slow terminal emulators.
40
41## Building/Installing
42
43See [doc/INSTALL](doc/INSTALL) for more details. Make sure you have read the Prerequisites section and satisified all the requirements.
44
45First, clone this repository, open a terminal window, and navigate to the repo directory.
46
47Run the following commands:
48
49```Shell
50./autogen.sh
51./configure
52make -j3
53sudo make install
54```
55
56## Uninstalling
57
58To uninstall **neo**, run the following command from the directory where you built neo:
59
60```Shell
61sudo make uninstall
62```
63
64**neo** can also be manually uninstalled by simply deleting the installed neo executable and neo.6 man page.
65
66## Running
67
68Once **neo** is installed, simply run:
69
70```Shell
71neo
72```
73
74**neo** has many options and key controls, arguably *too* many, and definitely too many to list here. Check the help message and manual for more info:
75
76```Shell
77neo -h
78man neo
79```
80
81## Screenshots
82
83![In Soviet Russia](assets/in_soviet_russia.png)
84
85![Green Hexadecimal](assets/green_hex.png)
86
87![Golden Greek](assets/golden_greek.png)
88
89## FAQ/Troubleshooting
90
91###
92**Q:** **neo** displays garbage characters on the screen. How can this be fixed?
93
94**A:** **neo** will attempt to use half-width katakana characters by default. You may not have a font installed that can display them correctly, or your terminal might not support Unicode well. Try "--charset=ascii" or changing your font. You may also need to use the "--colormode=0" option to disable color.
95
96###
97**Q:** Colors aren't working. How can this be fixed?
98
99**A:** Make sure your terminal supports colors. Double check if you need to set the TERM environment variable to enable colors. You may want to try the "--colormode" option.
100
101###
102**Q:** How do I disable the blinking characters?
103
104**A:** Use the --noglitch option.
105
106###
107**Q:** Can I make the text scroll faster or slower?
108
109**A:** Yes, use the -S/--speed option. Also, the UP and DOWN keys change the speed. The --async option may be fun to try.
110
111###
112**Q:** How do I change the colors?
113
114**A:** Use the -c/--color option (e.g. "-c red"). The number keys also change the color while running. Check out the "COLOR FILE" section in the manual if you want to customize **neo** with your own colors.
115
116###
117**Q:** How do I change the characters displayed?
118
119**A:** Use the --charset and/or --chars option. You may also need to use the -F/--fullwidth option depending on the characters you selected.
120
121###
122**Q:** How do I display a message in the center of the screen?
123
124**A:** Use the -m/--message option. Don't forget to use double quotes!
125
126###
127**Q:** neo just shows simple ASCII characters. How can I make it show Unicode characters?
128
129**A:** neo detects if your locale supports Unicode. Typically, your $LANG environment variable should have "UTF" somewhere if it does (e.g. "en_US.UTF-8"). You can use commands such as localectl to change these settings. You can force **neo** to attempt to use Unicode by setting a custom charset (e.g. --charset=extended), but this still may not work due to other OS and terminal settings.
130
131## Bugs
132
133File a GitHub issue. Crashes and build failures will be prioritized. Minor bugs, documentation errors, etc should hopefully get triaged and fixed... eventually.
134
135## Contributing
136
137See [doc/HACKING](doc/HACKING) for more implementation details and a list of things that could be improved.
138
139Requests for enhancement (RFEs) are not likely to be considered or implemented unless they are:
140
141- Within the scope of the original application
142- Simple
143- Likely to be used by more than one person
144
145The original author deliberately avoided some features present in similar projects (e.g. custom fonts and Windows support) for simplicity.
146
147Pull requests will be handled in a similar manner. Pull requests for bug fixes are more likely to be accepted than new features.
148
149## Acknowledgments
150
151- Chris Allegretta, the original author of cmatrix, and Abishek V Ashok, its current maintainer. cmatrix was a source of inspiration for **neo**.
152- Thomas E. Dickey, because **neo** would have been a PITA to write without ncursesw
153- Everyone involved in the production of "The Matrix" and the rest of the franchise
154
155## License
156
157**neo** is provided under the GNU GPL v3. See [doc/COPYING](doc/COPYING) for more details.
158
159## Disclaimer
160
161This project is not affiliated with "The Matrix", Warner Bros. Entertainment Inc., Village Roadshow Pictures, Silver Pictures, nor any of their parent companies, subsidiaries, partners, or affiliates.
162